@namzu/sdk 0.1.1

package/src/connector/BaseConnector.ts

@@ -0,0 +1,81 @@
+import type {
+  ConnectorDefinition,
+  ConnectorLifecycle,
+  ConnectorExecuteResult,
+  ConnectorMethod,
+  ConnectionType,
+  AuthConfig,
+} from '../types/connector/index.js'
+import type { z } from 'zod'
+import { getRootLogger, type Logger } from '../utils/logger.js'
+
+export abstract class BaseConnector<TConfig = unknown>
+  implements ConnectorLifecycle<TConfig>
+{
+  abstract readonly id: string
+  abstract readonly name: string
+  abstract readonly description: string
+  abstract readonly connectionType: ConnectionType
+  abstract readonly configSchema: z.ZodType<TConfig, z.ZodTypeDef, unknown>
+  abstract readonly methods: ConnectorMethod[]
+
+  protected log: Logger
+  protected config: TConfig | null = null
+  protected auth: AuthConfig | undefined
+
+  constructor() {
+    this.log = getRootLogger().child({ component: this.constructor.name })
+  }
+
+  abstract connect(config: TConfig, auth?: AuthConfig): Promise<void>
+  abstract disconnect(): Promise<void>
+  abstract healthCheck(): Promise<boolean>
+  abstract execute(method: string, input: unknown): Promise<ConnectorExecuteResult>
+
+  toDefinition(): ConnectorDefinition<TConfig> {
+    return {
+      id: this.id,
+      name: this.name,
+      description: this.description,
+      connectionType: this.connectionType,
+      configSchema: this.configSchema,
+      methods: this.methods,
+    }
+  }
+
+  protected findMethod(methodName: string): ConnectorMethod | undefined {
+    return this.methods.find((m) => m.name === methodName)
+  }
+
+  protected requireMethod(methodName: string): ConnectorMethod {
+    const method = this.findMethod(methodName)
+    if (!method) {
+      throw new Error(
+        `Method "${methodName}" not found on connector "${this.id}". ` +
+          `Available: ${this.methods.map((m) => m.name).join(', ')}`,
+      )
+    }
+    return method
+  }
+
+  protected validateInput(method: ConnectorMethod, input: unknown): unknown {
+    const result = method.inputSchema.safeParse(input)
+    if (!result.success) {
+      const errors = result.error.issues
+        .map((i) => `${i.path.join('.')}: ${i.message}`)
+        .join('; ')
+      throw new Error(`Invalid input for method "${method.name}": ${errors}`)
+    }
+    return result.data
+  }
+
+  protected measureExecution<TResult>(
+    fn: () => Promise<TResult>,
+  ): Promise<{ result: TResult; durationMs: number }> {
+    const start = performance.now()
+    return fn().then((result) => ({
+      result,
+      durationMs: Math.round(performance.now() - start),
+    }))
+  }
+}

package/src/connector/builtins/http.ts

@@ -0,0 +1,189 @@
+import { z } from 'zod'
+import { BaseConnector } from '../BaseConnector.js'
+import type {
+  ConnectionType,
+  ConnectorMethod,
+  ConnectorExecuteResult,
+  AuthConfig,
+  HttpConnectorConfig,
+  HttpRequestInput,
+  HttpResponseOutput,
+} from '../../types/connector/index.js'
+
+const HttpConnectorConfigSchema = z.object({
+  baseUrl: z.string().url(),
+  defaultHeaders: z.record(z.string()).optional(),
+  timeoutMs: z.number().positive().optional().default(30_000),
+})
+
+const HttpRequestInputSchema = z.object({
+  method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD']),
+  path: z.string(),
+  headers: z.record(z.string()).optional(),
+  query: z.record(z.string()).optional(),
+  body: z.unknown().optional(),
+})
+
+export class HttpConnector extends BaseConnector<HttpConnectorConfig> {
+  readonly id = 'http'
+  readonly name = 'HTTP Connector'
+  readonly description = 'Generic HTTP/REST API connector for making HTTP requests'
+  readonly connectionType: ConnectionType = 'http'
+  readonly configSchema = HttpConnectorConfigSchema
+  readonly methods: ConnectorMethod[] = [
+    {
+      name: 'request',
+      description: 'Make an HTTP request to the configured base URL',
+      inputSchema: HttpRequestInputSchema,
+    },
+  ]
+
+  private baseUrl = ''
+  private defaultHeaders: Record<string, string> = {}
+  private timeoutMs = 30_000
+
+  async connect(config: HttpConnectorConfig, auth?: AuthConfig): Promise<void> {
+    this.config = config
+    this.auth = auth
+    this.baseUrl = config.baseUrl.replace(/\/+$/, '')
+    this.defaultHeaders = config.defaultHeaders ?? {}
+    this.timeoutMs = config.timeoutMs ?? 30_000
+
+    if (auth) {
+      Object.assign(this.defaultHeaders, this.resolveAuthHeaders(auth))
+    }
+
+    this.log.info(`HTTP connector connected to ${this.baseUrl}`)
+  }
+
+  async disconnect(): Promise<void> {
+    this.config = null
+    this.auth = undefined
+    this.baseUrl = ''
+    this.defaultHeaders = {}
+    this.log.info('HTTP connector disconnected')
+  }
+
+  async healthCheck(): Promise<boolean> {
+    if (!this.baseUrl) return false
+    try {
+      const controller = new AbortController()
+      const timeout = setTimeout(() => controller.abort(), 5_000)
+      const response = await fetch(this.baseUrl, {
+        method: 'HEAD',
+        signal: controller.signal,
+      })
+      clearTimeout(timeout)
+      return response.ok || response.status < 500
+    } catch {
+      return false
+    }
+  }
+
+  async execute(method: string, input: unknown): Promise<ConnectorExecuteResult> {
+    this.requireMethod(method)
+    const validated = this.validateInput(
+      this.requireMethod(method),
+      input,
+    ) as HttpRequestInput
+
+    const { result, durationMs } = await this.measureExecution(() =>
+      this.doRequest(validated),
+    )
+
+    return {
+      success: result.status >= 200 && result.status < 400,
+      output: result,
+      durationMs,
+      metadata: {
+        status: result.status,
+        statusText: result.statusText,
+      },
+    }
+  }
+
+  private async doRequest(input: HttpRequestInput): Promise<HttpResponseOutput> {
+    const url = new URL(input.path, this.baseUrl + '/')
+    if (input.query) {
+      for (const [key, value] of Object.entries(input.query)) {
+        url.searchParams.set(key, value)
+      }
+    }
+
+    const headers: Record<string, string> = {
+      ...this.defaultHeaders,
+      ...input.headers,
+    }
+
+    if (input.body && !headers['content-type'] && !headers['Content-Type']) {
+      headers['Content-Type'] = 'application/json'
+    }
+
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs)
+
+    try {
+      const response = await fetch(url.toString(), {
+        method: input.method,
+        headers,
+        body: input.body !== undefined ? JSON.stringify(input.body) : undefined,
+        signal: controller.signal,
+      })
+
+      const responseHeaders: Record<string, string> = {}
+      response.headers.forEach((value, key) => {
+        responseHeaders[key] = value
+      })
+
+      let body: unknown
+      const contentType = response.headers.get('content-type') ?? ''
+      if (contentType.includes('application/json')) {
+        body = await response.json()
+      } else {
+        body = await response.text()
+      }
+
+      return {
+        status: response.status,
+        statusText: response.statusText,
+        headers: responseHeaders,
+        body,
+      }
+    } finally {
+      clearTimeout(timeout)
+    }
+  }
+
+  private resolveAuthHeaders(auth: AuthConfig): Record<string, string> {
+    const creds = auth.credentials ?? {}
+    switch (auth.type) {
+      case 'api_key': {
+        const apiKey = creds['apiKey']
+        if (!apiKey) throw new Error('AuthConfig api_key: missing required credential "apiKey"')
+        return {
+          [creds['headerName'] ?? 'X-API-Key']: apiKey,
+        }
+      }
+      case 'bearer': {
+        const token = creds['token']
+        if (!token) throw new Error('AuthConfig bearer: missing required credential "token"')
+        return { Authorization: `Bearer ${token}` }
+      }
+      case 'basic': {
+        const username = creds['username']
+        const password = creds['password']
+        if (!username || !password) throw new Error('AuthConfig basic: missing required credentials "username" and "password"')
+        const encoded = btoa(`${username}:${password}`)
+        return { Authorization: `Basic ${encoded}` }
+      }
+      case 'none':
+      case 'oauth2':
+      case 'custom':
+        return {}
+      default: {
+        const _exhaustive: never = auth.type
+        throw new Error(`Unhandled auth type: ${_exhaustive}`)
+      }
+    }
+  }
+}

package/src/connector/builtins/index.ts

@@ -0,0 +1,2 @@
+export { HttpConnector } from './http.js'
+export { WebhookConnector } from './webhook.js'

package/src/connector/builtins/webhook.ts

@@ -0,0 +1,153 @@
+import { z } from 'zod'
+import { createHmac } from 'node:crypto'
+import { BaseConnector } from '../BaseConnector.js'
+import type {
+  ConnectionType,
+  ConnectorMethod,
+  ConnectorExecuteResult,
+  AuthConfig,
+  WebhookConnectorConfig,
+  WebhookSendInput,
+  WebhookSendOutput,
+} from '../../types/connector/index.js'
+
+const WebhookConnectorConfigSchema = z.object({
+  url: z.string().url(),
+  secret: z.string().optional(),
+  defaultHeaders: z.record(z.string()).optional(),
+  timeoutMs: z.number().positive().optional().default(30_000),
+})
+
+const WebhookSendInputSchema = z.object({
+  payload: z.unknown(),
+  headers: z.record(z.string()).optional(),
+  url: z.string().url().optional(),
+})
+
+export class WebhookConnector extends BaseConnector<WebhookConnectorConfig> {
+  readonly id = 'webhook'
+  readonly name = 'Webhook Connector'
+  readonly description = 'Send webhook payloads to configured endpoints with optional HMAC signing'
+  readonly connectionType: ConnectionType = 'webhook'
+  readonly configSchema = WebhookConnectorConfigSchema
+  readonly methods: ConnectorMethod[] = [
+    {
+      name: 'send',
+      description: 'Send a webhook payload to the configured URL',
+      inputSchema: WebhookSendInputSchema,
+    },
+  ]
+
+  private url = ''
+  private secret: string | undefined
+  private defaultHeaders: Record<string, string> = {}
+  private timeoutMs = 30_000
+
+  async connect(config: WebhookConnectorConfig, auth?: AuthConfig): Promise<void> {
+    this.config = config
+    this.auth = auth
+    this.url = config.url
+    this.secret = config.secret
+    this.defaultHeaders = config.defaultHeaders ?? {}
+    this.timeoutMs = config.timeoutMs ?? 30_000
+
+    if (auth?.type === 'bearer' && auth.credentials?.['token']) {
+      this.defaultHeaders['Authorization'] = `Bearer ${auth.credentials['token']}`
+    }
+
+    this.log.info(`Webhook connector connected to ${this.url}`)
+  }
+
+  async disconnect(): Promise<void> {
+    this.config = null
+    this.auth = undefined
+    this.url = ''
+    this.secret = undefined
+    this.defaultHeaders = {}
+    this.log.info('Webhook connector disconnected')
+  }
+
+  async healthCheck(): Promise<boolean> {
+    if (!this.url) return false
+    try {
+      const controller = new AbortController()
+      const timeout = setTimeout(() => controller.abort(), 5_000)
+      const response = await fetch(this.url, {
+        method: 'HEAD',
+        signal: controller.signal,
+      })
+      clearTimeout(timeout)
+      return response.ok || response.status < 500
+    } catch {
+      return false
+    }
+  }
+
+  async execute(method: string, input: unknown): Promise<ConnectorExecuteResult> {
+    this.requireMethod(method)
+    const validated = this.validateInput(
+      this.requireMethod(method),
+      input,
+    ) as WebhookSendInput
+
+    const { result, durationMs } = await this.measureExecution(() =>
+      this.doSend(validated),
+    )
+
+    return {
+      success: result.status >= 200 && result.status < 400,
+      output: result,
+      durationMs,
+      metadata: {
+        status: result.status,
+        deliveredAt: result.deliveredAt,
+      },
+    }
+  }
+
+  private async doSend(input: WebhookSendInput): Promise<WebhookSendOutput> {
+    const targetUrl = input.url ?? this.url
+    const bodyStr = JSON.stringify(input.payload)
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...this.defaultHeaders,
+      ...input.headers,
+    }
+
+    if (this.secret) {
+      const signature = createHmac('sha256', this.secret)
+        .update(bodyStr)
+        .digest('hex')
+      headers['X-Webhook-Signature'] = `sha256=${signature}`
+    }
+
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs)
+
+    try {
+      const response = await fetch(targetUrl, {
+        method: 'POST',
+        headers,
+        body: bodyStr,
+        signal: controller.signal,
+      })
+
+      let body: unknown
+      const contentType = response.headers.get('content-type') ?? ''
+      if (contentType.includes('application/json')) {
+        body = await response.json()
+      } else {
+        body = await response.text()
+      }
+
+      return {
+        status: response.status,
+        body,
+        deliveredAt: Date.now(),
+      }
+    } finally {
+      clearTimeout(timeout)
+    }
+  }
+}

package/src/connector/execution/factory.ts

@@ -0,0 +1,53 @@
+import { type ExecutionContextConfig, type ConnectorExecutionContextEvent } from '../../types/connector/index.js'
+import type { BaseExecutionContext } from '../../execution/base.js'
+import { type LocalExecutionContextOptions, LocalExecutionContext } from '../../execution/local.js'
+import { type RemoteExecutionContextOptions, RemoteExecutionContext } from './remote.js'
+import { type HybridExecutionContextOptions, HybridExecutionContext } from './hybrid.js'
+
+export class ExecutionContextFactory {
+  static create(config: ExecutionContextConfig): BaseExecutionContext {
+    switch (config.environment) {
+      case 'local':
+        return ExecutionContextFactory.createLocal({
+          id: config.id,
+          cwd: config.cwd,
+          fsAccess: config.fsAccess,
+          envVars: config.envVars,
+          capabilities: config.capabilities,
+          shell: config.shell,
+        })
+
+      case 'remote':
+        return ExecutionContextFactory.createRemote({
+          id: config.id,
+          target: config.target,
+          capabilities: config.capabilities,
+        })
+
+      case 'hybrid':
+        return ExecutionContextFactory.createHybrid({
+          id: config.id,
+          local: config.local,
+          remotes: config.remotes,
+          routingStrategy: config.routingStrategy,
+        })
+
+      default: {
+        const _exhaustive: never = config
+        throw new Error(`Unhandled execution environment: ${JSON.stringify(_exhaustive)}`)
+      }
+    }
+  }
+
+  static createLocal(options: LocalExecutionContextOptions): LocalExecutionContext {
+    return new LocalExecutionContext(options)
+  }
+
+  static createRemote(options: RemoteExecutionContextOptions): RemoteExecutionContext {
+    return new RemoteExecutionContext(options)
+  }
+
+  static createHybrid(options: HybridExecutionContextOptions): HybridExecutionContext {
+    return new HybridExecutionContext(options)
+  }
+}

package/src/connector/execution/hybrid.ts

@@ -0,0 +1,201 @@
+import type {
+  ExecutionEnvironment,
+  ExecutionCapability,
+  HybridExecutionContextConfig,
+  RemoteTarget,
+  ConnectorExecutionContextEvent,
+  ExecutionRoutingStrategy,
+  CommandOptions,
+  CommandResult,
+  CommandExecutor,
+} from '../../types/connector/index.js'
+import { BaseExecutionContext } from '../../execution/base.js'
+import { LocalExecutionContext } from '../../execution/local.js'
+import { RemoteExecutionContext } from './remote.js'
+
+export interface HybridExecutionContextOptions {
+  id: string
+  local: {
+    cwd: string
+    fsAccess?: boolean
+    envVars?: Record<string, string>
+    capabilities?: ExecutionCapability[]
+    shell?: string
+  }
+  remotes: RemoteTarget[]
+  routingStrategy?: ExecutionRoutingStrategy
+}
+
+export class HybridExecutionContext extends BaseExecutionContext implements CommandExecutor {
+  readonly id: string
+  readonly environment: ExecutionEnvironment = 'hybrid'
+
+  private localCtx: LocalExecutionContext
+  private remoteCtxs: Map<string, RemoteExecutionContext> = new Map()
+  private remoteTargets: RemoteTarget[]
+  private routingStrategy: ExecutionRoutingStrategy
+  private roundRobinIndex = 0
+
+  constructor(options: HybridExecutionContextOptions) {
+    super()
+    this.id = options.id
+    this.remoteTargets = options.remotes
+    this.routingStrategy = options.routingStrategy ?? 'local-first'
+
+    this.localCtx = new LocalExecutionContext({
+      id: `${options.id}_local`,
+      cwd: options.local.cwd,
+      fsAccess: options.local.fsAccess,
+      envVars: options.local.envVars,
+      capabilities: options.local.capabilities,
+      shell: options.local.shell,
+    })
+
+    this.localCtx.on((event) => this.emit(event))
+
+    for (let i = 0; i < options.remotes.length; i++) {
+      const target = options.remotes[i]!
+      const remoteId = `${options.id}_remote_${i}`
+      const remote = new RemoteExecutionContext({
+        id: remoteId,
+        target,
+      })
+      remote.on((event) => this.emit(event))
+      this.remoteCtxs.set(remoteId, remote)
+    }
+  }
+
+  protected async doInitialize(): Promise<void> {
+    await this.localCtx.initialize()
+
+    const initPromises: Promise<void>[] = []
+    for (const remote of this.remoteCtxs.values()) {
+      initPromises.push(remote.initialize())
+    }
+    await Promise.all(initPromises)
+
+    this.log.info(
+      `Hybrid context initialized: local(${this.localCtx.getCwd()}) + ${this.remoteCtxs.size} remote(s), strategy=${this.routingStrategy}`,
+    )
+  }
+
+  protected async doTeardown(): Promise<void> {
+    const teardownPromises: Promise<void>[] = []
+    for (const remote of this.remoteCtxs.values()) {
+      teardownPromises.push(remote.teardown())
+    }
+    await Promise.allSettled(teardownPromises)
+    await this.localCtx.teardown()
+  }
+
+  getLocal(): LocalExecutionContext {
+    return this.localCtx
+  }
+
+  getRemote(remoteId: string): RemoteExecutionContext | undefined {
+    return this.remoteCtxs.get(remoteId)
+  }
+
+  getRemotes(): RemoteExecutionContext[] {
+    return Array.from(this.remoteCtxs.values())
+  }
+
+  getRoutingStrategy(): ExecutionRoutingStrategy {
+    return this.routingStrategy
+  }
+
+  setRoutingStrategy(strategy: ExecutionRoutingStrategy): void {
+    this.routingStrategy = strategy
+    this.roundRobinIndex = 0
+  }
+
+  async connectAllRemotes(): Promise<void> {
+    const promises: Promise<void>[] = []
+    for (const remote of this.remoteCtxs.values()) {
+      promises.push(remote.connect())
+    }
+    await Promise.all(promises)
+  }
+
+  async disconnectAllRemotes(): Promise<void> {
+    const promises: Promise<void>[] = []
+    for (const remote of this.remoteCtxs.values()) {
+      promises.push(remote.disconnect())
+    }
+    await Promise.allSettled(promises)
+  }
+
+  async executeCommand(
+    command: string,
+    args: string[] = [],
+    options?: CommandOptions,
+  ): Promise<CommandResult> {
+    switch (this.routingStrategy) {
+      case 'local-first':
+        return this.localCtx.executeCommand(command, args, options)
+
+      case 'remote-first': {
+        const connectedRemote = this.getFirstConnectedRemote()
+        if (connectedRemote) {
+          const fullCommand = args.length > 0 ? `${command} ${args.join(' ')}` : command
+          return connectedRemote.executeRemote(fullCommand, options)
+        }
+        return this.localCtx.executeCommand(command, args, options)
+      }
+
+      case 'round-robin': {
+        const targets = this.getRoundRobinTargets()
+        if (targets.length === 0) {
+          return this.localCtx.executeCommand(command, args, options)
+        }
+        const targetIndex = this.roundRobinIndex % targets.length
+        this.roundRobinIndex++
+        const target = targets[targetIndex]!
+
+        if (target === this.localCtx) {
+          return this.localCtx.executeCommand(command, args, options)
+        }
+        const fullCommand = args.length > 0 ? `${command} ${args.join(' ')}` : command
+        return (target as RemoteExecutionContext).executeRemote(fullCommand, options)
+      }
+
+      default: {
+        const _exhaustive: never = this.routingStrategy
+        throw new Error(`Unhandled routing strategy: ${_exhaustive}`)
+      }
+    }
+  }
+
+  toConfig(): HybridExecutionContextConfig {
+    return {
+      id: this.id,
+      environment: 'hybrid',
+      local: {
+        cwd: this.localCtx.getCwd(),
+        fsAccess: this.localCtx.hasFsAccess(),
+        envVars: this.localCtx.getEnvVars(),
+      },
+      remotes: this.remoteTargets.map((t) => ({ ...t })),
+      routingStrategy: this.routingStrategy,
+    }
+  }
+
+  private getFirstConnectedRemote(): RemoteExecutionContext | undefined {
+    for (const remote of this.remoteCtxs.values()) {
+      if (remote.isConnected()) {
+        return remote
+      }
+    }
+    return undefined
+  }
+
+  private getRoundRobinTargets(): (LocalExecutionContext | RemoteExecutionContext)[] {
+    const targets: (LocalExecutionContext | RemoteExecutionContext)[] = [this.localCtx]
+    for (const remote of this.remoteCtxs.values()) {
+      if (remote.isConnected()) {
+        targets.push(remote)
+      }
+    }
+    return targets
+  }
+}

package/src/connector/execution/index.ts

@@ -0,0 +1,5 @@
+export { RemoteExecutionContext } from './remote.js'
+export type { RemoteExecutionContextOptions } from './remote.js'
+export { HybridExecutionContext } from './hybrid.js'
+export type { HybridExecutionContextOptions } from './hybrid.js'
+export { ExecutionContextFactory } from './factory.js'