@soederpop/luca 0.0.2

package/src/node/features/port-exposer.ts

@@ -0,0 +1,342 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import * as ngrok from '@ngrok/ngrok'
+import { Feature, features } from '../../feature.js'
+
+/**
+ * Zod schema for the Port Exposer feature state
+ */
+export const PortExposerStateSchema = FeatureStateSchema.extend({
+	/** Whether ngrok is currently connected */
+	connected: z.boolean().describe('Whether ngrok is currently connected'),
+	/** The public URL provided by ngrok */
+	publicUrl: z.string().optional().describe('The public URL provided by ngrok'),
+	/** The local port being exposed */
+	localPort: z.number().optional().describe('The local port being exposed'),
+	/** Ngrok session information */
+	sessionInfo: z.object({
+		authToken: z.string().optional().describe('Ngrok authentication token'),
+		region: z.string().optional().describe('Ngrok region'),
+		subdomain: z.string().optional().describe('Ngrok subdomain'),
+	}).optional().describe('Ngrok session information'),
+	/** Connection timestamp */
+	connectedAt: z.coerce.date().optional().describe('Timestamp when the connection was established'),
+	/** Any error that occurred */
+	lastError: z.string().optional().describe('Last error message from an ngrok operation'),
+})
+export type PortExposerState = z.infer<typeof PortExposerStateSchema>
+
+/**
+ * Zod schema for Port Exposer feature options
+ */
+export const PortExposerOptionsSchema = FeatureOptionsSchema.extend({
+	/** Local port to expose */
+	port: z.number().optional().describe('Local port to expose'),
+	/** Optional ngrok auth token for premium features */
+	authToken: z.string().optional().describe('Ngrok auth token for premium features'),
+	/** Preferred region (us, eu, ap, au, sa, jp, in) */
+	region: z.string().optional().describe('Preferred ngrok region (us, eu, ap, au, sa, jp, in)'),
+	/** Custom subdomain (requires paid plan) */
+	subdomain: z.string().optional().describe('Custom subdomain (requires paid plan)'),
+	/** Domain to use (requires paid plan) */
+	domain: z.string().optional().describe('Domain to use (requires paid plan)'),
+	/** Basic auth for the tunnel */
+	basicAuth: z.string().optional().describe('Basic auth credentials for the tunnel'),
+	/** OAuth provider for authentication */
+	oauth: z.string().optional().describe('OAuth provider for authentication'),
+	/** Additional ngrok configuration */
+	config: z.any().describe('Additional ngrok configuration'),
+})
+export type PortExposerOptions = z.infer<typeof PortExposerOptionsSchema>
+
+/**
+ * Port Exposer Feature
+ * 
+ * Exposes local HTTP services via ngrok with SSL-enabled public URLs.
+ * Perfect for development, testing, and sharing local services securely.
+ * 
+ * Features:
+ * - SSL-enabled public URLs for local services
+ * - Custom subdomains and domains (with paid plans)
+ * - Authentication options (basic auth, OAuth)
+ * - Regional endpoint selection
+ * - Connection state management
+ * 
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const exposer = container.feature('portExposer', { port: 3000 })
+ * const url = await exposer.expose()
+ * console.log(`Service available at: ${url}`)
+ *
+ * // With custom subdomain
+ * const exposer = container.feature('portExposer', {
+ *   port: 8080,
+ *   subdomain: 'my-app',
+ *   authToken: 'your-ngrok-token'
+ * })
+ * ```
+ */
+export class PortExposer extends Feature<PortExposerState, PortExposerOptions> {
+	static override shortcut = 'portExposer' as const
+	static override stateSchema = PortExposerStateSchema
+	static override optionsSchema = PortExposerOptionsSchema
+
+	private ngrokListener?: ngrok.Listener
+
+	override get initialState(): PortExposerState {
+		return {
+			...super.initialState,
+			connected: false
+		}
+	}
+
+	/**
+	 * Expose the local port via ngrok.
+	 *
+	 * Creates an ngrok tunnel to the specified local port and returns
+	 * the SSL-enabled public URL. Emits `exposed` on success or `error` on failure.
+	 *
+	 * @param port - Optional port override; falls back to `options.port`
+	 * @returns Promise resolving to the public URL string
+	 * @throws {Error} When no port is specified in options or parameter
+	 *
+	 * @example
+	 * ```typescript
+	 * const exposer = container.feature('portExposer', { port: 3000 })
+	 * const url = await exposer.expose()
+	 * console.log(`Public URL: ${url}`)
+	 *
+	 * // Override port at call time
+	 * const url2 = await exposer.expose(8080)
+	 * ```
+	 */
+	async expose(port?: number): Promise<string> {
+		const targetPort = port || this.options.port
+		
+		if (!targetPort) {
+			throw new Error('Port must be specified either in options or as parameter')
+		}
+
+		try {
+			// Set up ngrok configuration
+			const config: any = {
+				addr: targetPort,
+				...this.options.config
+			}
+
+			// Add optional configuration
+			if (this.options.authToken) {
+				config.authtoken = this.options.authToken
+			}
+			if (this.options.region) {
+				config.region = this.options.region
+			}
+			if (this.options.subdomain) {
+				config.subdomain = this.options.subdomain
+			}
+			if (this.options.domain) {
+				config.domain = this.options.domain
+			}
+			if (this.options.basicAuth) {
+				config.basic_auth = this.options.basicAuth
+			}
+			if (this.options.oauth) {
+				config.oauth = this.options.oauth
+			}
+
+			// Start ngrok listener
+			this.ngrokListener = await ngrok.forward(config)
+			const publicUrl = this.ngrokListener.url() || undefined
+
+			// Update state
+			this.setState({
+				connected: true,
+				publicUrl,
+				localPort: targetPort,
+				sessionInfo: {
+					authToken: this.options.authToken,
+					region: this.options.region,
+					subdomain: this.options.subdomain
+				},
+				connectedAt: new Date(),
+				lastError: undefined
+			})
+
+			this.emit('exposed', { publicUrl, localPort: targetPort })
+			
+			return publicUrl!
+
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+			
+			this.setState({
+				connected: false,
+				lastError: errorMessage
+			})
+
+			this.emit('error', error)
+			throw error
+		}
+	}
+
+	/**
+	 * Stop exposing the port and close the ngrok tunnel.
+	 *
+	 * Tears down the ngrok listener, resets connection state, and emits `closed`.
+	 * Safe to call when no tunnel is active (no-op).
+	 *
+	 * @returns Promise that resolves when the tunnel is fully closed
+	 * @throws {Error} When the ngrok listener fails to close
+	 *
+	 * @example
+	 * ```typescript
+	 * const exposer = container.feature('portExposer', { port: 3000 })
+	 * await exposer.expose()
+	 * // ... later
+	 * await exposer.close()
+	 * console.log(exposer.isConnected()) // false
+	 * ```
+	 */
+	async close(): Promise<void> {
+		if (this.ngrokListener) {
+			try {
+				await this.ngrokListener.close()
+				this.ngrokListener = undefined
+
+				this.setState({
+					connected: false,
+					publicUrl: undefined,
+					localPort: undefined,
+					connectedAt: undefined
+				})
+
+				this.emit('closed')
+			} catch (error) {
+				const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+				this.setState({ lastError: errorMessage })
+				this.emit('error', error)
+				throw error
+			}
+		}
+	}
+
+	/**
+	 * Get the current public URL if connected.
+	 *
+	 * Returns the live URL from the ngrok listener, or `undefined` if no tunnel is active.
+	 *
+	 * @returns The public HTTPS URL string, or undefined when disconnected
+	 *
+	 * @example
+	 * ```typescript
+	 * const exposer = container.feature('portExposer', { port: 3000 })
+	 * await exposer.expose()
+	 * console.log(exposer.getPublicUrl()) // 'https://abc123.ngrok.io'
+	 * ```
+	 */
+	getPublicUrl(): string | undefined {
+		return this.ngrokListener?.url() || undefined
+	}
+
+	/**
+	 * Check if the ngrok tunnel is currently connected.
+	 *
+	 * @returns `true` when an active tunnel exists, `false` otherwise
+	 *
+	 * @example
+	 * ```typescript
+	 * const exposer = container.feature('portExposer', { port: 3000 })
+	 * console.log(exposer.isConnected()) // false
+	 * await exposer.expose()
+	 * console.log(exposer.isConnected()) // true
+	 * ```
+	 */
+	isConnected(): boolean {
+		return this.state.get('connected') ?? false
+	}
+
+	/**
+	 * Get a snapshot of the current connection information.
+	 *
+	 * Returns an object with the tunnel's connected status, public URL,
+	 * local port, connection timestamp, and session metadata.
+	 *
+	 * @returns An object containing `connected`, `publicUrl`, `localPort`, `connectedAt`, and `sessionInfo`
+	 *
+	 * @example
+	 * ```typescript
+	 * const exposer = container.feature('portExposer', { port: 3000 })
+	 * await exposer.expose()
+	 * const info = exposer.getConnectionInfo()
+	 * console.log(info.publicUrl, info.localPort, info.connectedAt)
+	 * ```
+	 */
+	getConnectionInfo() {
+		const state = this.state.current
+		return {
+			connected: state.connected,
+			publicUrl: state.publicUrl,
+			localPort: state.localPort,
+			connectedAt: state.connectedAt,
+			sessionInfo: state.sessionInfo
+		}
+	}
+
+	/**
+	 * Close the existing tunnel and re-expose with optionally updated options.
+	 *
+	 * Calls `close()` first, merges any new options, then calls `expose()`.
+	 *
+	 * @param newOptions - Optional partial options to merge before reconnecting
+	 * @returns Promise resolving to the new public URL string
+	 *
+	 * @example
+	 * ```typescript
+	 * const exposer = container.feature('portExposer', { port: 3000 })
+	 * await exposer.expose()
+	 * // Switch to a different port
+	 * const newUrl = await exposer.reconnect({ port: 8080 })
+	 * ```
+	 */
+	async reconnect(newOptions?: Partial<PortExposerOptions>): Promise<string> {
+		await this.close()
+		
+		if (newOptions) {
+			Object.assign(this.options, newOptions)
+		}
+
+		return this.expose()
+	}
+
+	/**
+	 * Disable the feature, ensuring the ngrok tunnel is closed first.
+	 *
+	 * Overrides the base `disable()` to guarantee that the tunnel is
+	 * torn down before the feature is marked as disabled.
+	 *
+	 * @returns This PortExposer instance
+	 *
+	 * @example
+	 * ```typescript
+	 * const exposer = container.feature('portExposer', { port: 3000 })
+	 * await exposer.expose()
+	 * await exposer.disable()
+	 * ```
+	 */
+	async disable(): Promise<this> {
+		await this.close()
+		return this
+	}
+}
+
+// Register the feature with the features registry
+export default features.register('portExposer', PortExposer)
+
+// Module augmentation for type safety
+declare module '../../feature.js' {
+	interface AvailableFeatures {
+		portExposer: typeof PortExposer
+	}
+}
+

package/src/node/features/postgres.ts

@@ -0,0 +1,273 @@
+import { z } from 'zod'
+import { SQL } from 'bun'
+import { Feature, features } from '../feature.js'
+import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import type { ContainerContext } from '../../container.js'
+
+type SqlValue = string | number | boolean | bigint | Uint8Array | Buffer | null
+
+export const PostgresStateSchema = FeatureStateSchema.extend({
+  connected: z.boolean().default(false).describe('Whether the postgres connection is currently open'),
+  url: z.string().default('').describe('Connection URL used for this postgres feature instance'),
+  lastQuery: z.string().optional().describe('Most recent SQL query string that was executed'),
+  lastRowCount: z.number().optional().describe('Row count returned by the most recent query execution'),
+  lastError: z.string().optional().describe('Most recent postgres error message, if any'),
+})
+
+export const PostgresOptionsSchema = FeatureOptionsSchema.extend({
+  url: z.string().min(1).optional().describe('Postgres connection URL, e.g. postgres://user:pass@host:5432/db'),
+})
+
+export type PostgresState = z.infer<typeof PostgresStateSchema>
+export type PostgresOptions = z.infer<typeof PostgresOptionsSchema>
+
+/**
+ * Postgres feature for safe SQL execution through Bun's native SQL client.
+ *
+ * Supports:
+ * - parameterized query execution (`query` / `execute`)
+ * - tagged-template query execution (`sql`) to avoid manual placeholder wiring
+ *
+ * @example
+ * ```typescript
+ * const postgres = container.feature('postgres', { url: process.env.DATABASE_URL! })
+ *
+ * const users = await postgres.query<{ id: number; email: string }>(
+ *   'select id, email from users where id = $1',
+ *   [123]
+ * )
+ *
+ * const rows = await postgres.sql<{ id: number }>`
+ *   select id from users where email = ${'hello@example.com'}
+ * `
+ * ```
+ */
+export class Postgres extends Feature<PostgresState, PostgresOptions> {
+  static override shortcut = 'features.postgres' as const
+  static override stateSchema = PostgresStateSchema
+  static override optionsSchema = PostgresOptionsSchema
+
+  private _client: SQL
+
+  /**
+   * Default state for the Postgres feature before a connection is established.
+   * @returns The initial PostgresState with `connected: false` and empty `url`
+   */
+  override get initialState(): PostgresState {
+    return {
+      enabled: false,
+      connected: false,
+      url: '',
+    }
+  }
+
+  constructor(options: PostgresOptions, context: ContainerContext) {
+    super(options, context)
+
+    if (!options.url) {
+      throw new Error('Postgres feature requires options.url')
+    }
+
+    this._client = new SQL(options.url)
+    this.hide('_client')
+
+    this.setState({
+      connected: true,
+      url: options.url,
+    })
+  }
+
+  /**
+   * Returns the underlying Bun SQL postgres client.
+   * @returns The raw `SQL` instance used for all database operations
+   */
+  get client() {
+    return this._client
+  }
+
+  /**
+   * Executes a SELECT-like query and returns result rows.
+   *
+   * Use postgres placeholders (`$1`, `$2`, ...) for `params`.
+   *
+   * @param queryText - The SQL query string with optional `$N` placeholders
+   * @param params - Ordered array of values to bind to the placeholders
+   * @returns Promise resolving to an array of typed result rows
+   * @throws {Error} When query text is empty or params contain `undefined`
+   *
+   * @example
+   * ```typescript
+   * const pg = container.feature('postgres', { url: process.env.DATABASE_URL! })
+   * const users = await pg.query<{ id: number; email: string }>(
+   *   'SELECT id, email FROM users WHERE active = $1',
+   *   [true]
+   * )
+   * ```
+   */
+  async query<T extends object = Record<string, unknown>>(queryText: string, params: SqlValue[] = []): Promise<T[]> {
+    assertQueryText(queryText)
+    assertParams(params)
+
+    try {
+      const result = await this.client.unsafe(queryText, params)
+      const rows = Array.isArray(result) ? result as T[] : []
+      const rowCount = resolveRowCount(result)
+
+      this.setState({
+        lastQuery: queryText,
+        lastRowCount: rowCount,
+        lastError: undefined,
+      })
+
+      this.emit('query', queryText, params, rowCount)
+      return rows
+    } catch (error: any) {
+      this.setState({
+        lastQuery: queryText,
+        lastError: error?.message || String(error),
+      })
+
+      this.emit('error', error)
+      throw error
+    }
+  }
+
+  /**
+   * Executes a write/update/delete statement and returns metadata.
+   *
+   * Use postgres placeholders (`$1`, `$2`, ...) for `params`.
+   *
+   * @param queryText - The SQL statement string with optional `$N` placeholders
+   * @param params - Ordered array of values to bind to the placeholders
+   * @returns Promise resolving to `{ rowCount }` indicating affected rows
+   * @throws {Error} When query text is empty or params contain `undefined`
+   *
+   * @example
+   * ```typescript
+   * const pg = container.feature('postgres', { url: process.env.DATABASE_URL! })
+   * const { rowCount } = await pg.execute(
+   *   'UPDATE users SET active = $1 WHERE last_login < $2',
+   *   [false, '2024-01-01']
+   * )
+   * console.log(`Deactivated ${rowCount} users`)
+   * ```
+   */
+  async execute(queryText: string, params: SqlValue[] = []): Promise<{ rowCount: number }> {
+    assertQueryText(queryText)
+    assertParams(params)
+
+    try {
+      const result = await this.client.unsafe(queryText, params)
+      const rowCount = resolveRowCount(result)
+
+      this.setState({
+        lastQuery: queryText,
+        lastRowCount: rowCount,
+        lastError: undefined,
+      })
+
+      this.emit('execute', queryText, params, rowCount)
+      return { rowCount }
+    } catch (error: any) {
+      this.setState({
+        lastQuery: queryText,
+        lastError: error?.message || String(error),
+      })
+
+      this.emit('error', error)
+      throw error
+    }
+  }
+
+  /**
+   * Safe tagged-template SQL helper.
+   *
+   * Values become bound parameters automatically, preventing SQL injection.
+   *
+   * @param strings - Template literal string segments
+   * @param values - Interpolated values that become bound `$N` parameters
+   * @returns Promise resolving to an array of typed result rows
+   *
+   * @example
+   * ```typescript
+   * const pg = container.feature('postgres', { url: process.env.DATABASE_URL! })
+   * const email = 'hello@example.com'
+   * const rows = await pg.sql<{ id: number }>`
+   *   SELECT id FROM users WHERE email = ${email}
+   * `
+   * ```
+   */
+  async sql<T extends object = Record<string, unknown>>(strings: TemplateStringsArray, ...values: SqlValue[]): Promise<T[]> {
+    const built = buildDollarQuery(strings, values)
+    return this.query<T>(built.text, built.params)
+  }
+
+  /**
+   * Closes the postgres connection and updates feature state.
+   *
+   * Emits `closed` after the connection is torn down.
+   *
+   * @returns This Postgres feature instance for method chaining
+   *
+   * @example
+   * ```typescript
+   * const pg = container.feature('postgres', { url: process.env.DATABASE_URL! })
+   * // ... run queries ...
+   * await pg.close()
+   * ```
+   */
+  async close() {
+    await this.client.close()
+    this.setState({ connected: false })
+    this.emit('closed')
+    return this
+  }
+}
+
+export default features.register('postgres', Postgres)
+
+declare module '../../feature.js' {
+  interface AvailableFeatures {
+    postgres: typeof Postgres
+  }
+}
+
+function assertQueryText(queryText: string) {
+  if (typeof queryText !== 'string' || queryText.trim().length === 0) {
+    throw new Error('SQL query text must be a non-empty string')
+  }
+}
+
+function assertParams(params: SqlValue[]) {
+  if (!Array.isArray(params)) {
+    throw new Error('SQL params must be an array')
+  }
+
+  if (params.some((param) => param === undefined)) {
+    throw new Error('SQL params cannot contain undefined values. Use null instead.')
+  }
+}
+
+function buildDollarQuery(strings: TemplateStringsArray, values: SqlValue[]) {
+  if (strings.length !== values.length + 1) {
+    throw new Error('Invalid SQL template literal input')
+  }
+
+  const chunks: string[] = []
+
+  for (let i = 0; i < strings.length; i++) {
+    chunks.push(strings[i]!)
+    if (i < values.length) {
+      chunks.push(`$${i + 1}`)
+    }
+  }
+
+  return { text: chunks.join(''), params: values }
+}
+
+function resolveRowCount(result: any): number {
+  if (typeof result?.count === 'number') return result.count
+  if (typeof result?.rowCount === 'number') return result.rowCount
+  if (Array.isArray(result)) return result.length
+  return 0
+}