@soederpop/luca 0.0.6 → 0.0.7

package/src/scaffolds/template.ts

@@ -13,6 +13,14 @@ export function toCamelCase(str: string): string {
 	return pascal.charAt(0).toLowerCase() + pascal.slice(1)
 }
 
+/** Convert a string to kebab-case */
+export function toKebabCase(str: string): string {
+	return str
+		.replace(/([a-z])([A-Z])/g, '$1-$2')
+		.replace(/[_\s]+/g, '-')
+		.toLowerCase()
+}
+
 /** Apply mustache-style template variables to scaffold code */
 export function applyTemplate(template: string, vars: Record<string, string>): string {
 	let result = template
@@ -30,6 +38,7 @@ export function generateScaffold(type: string, name: string, description?: strin
 	const vars = {
 		PascalName: toPascalCase(name),
 		camelName: toCamelCase(name),
+		kebabName: toKebabCase(name),
 		description: description || `A ${type} that does something useful`,
 	}
 

package/src/schemas/base.ts

@@ -154,14 +154,45 @@ export const CommandStateSchema = HelperStateSchema.extend({
 
 export const CommandOptionsSchema = HelperOptionsSchema.extend({
   _: z.array(z.string()).default([]).describe('Positional arguments from minimist'),
+  dispatchSource: z.enum(['cli', 'headless', 'mcp', 'rpc']).default('cli').describe('How this command was invoked — controls arg normalization and output capture'),
 }).describe('Base command options parsed from argv')
 
+export type DispatchSource = 'cli' | 'headless' | 'mcp' | 'rpc'
+
+export interface CommandRunResult {
+  exitCode: number
+  stdout: string
+  stderr: string
+}
+
 export const CommandEventsSchema = HelperEventsSchema.extend({
   started: z.tuple([]).describe('Emitted when command execution begins'),
   completed: z.tuple([z.number().describe('Exit code')]).describe('Emitted when command execution finishes'),
   failed: z.tuple([z.any().describe('The error')]).describe('Emitted when command execution fails'),
 }).describe('Base command events')
 
+// Selector schemas
+export const SelectorStateSchema = HelperStateSchema.extend({
+  running: z.boolean().default(false).describe('Whether the selector is currently running'),
+  lastRanAt: z.number().optional().describe('Unix timestamp of last successful run'),
+}).describe('Base selector state')
+
+export const SelectorOptionsSchema = HelperOptionsSchema.extend({
+  dispatchSource: z.enum(['cli', 'headless', 'mcp', 'rpc']).default('headless').describe('How this selector was invoked'),
+}).describe('Base selector options')
+
+export interface SelectorRunResult<T = any> {
+  data: T
+  cached: boolean
+  cacheKey: string
+}
+
+export const SelectorEventsSchema = HelperEventsSchema.extend({
+  started: z.tuple([]).describe('Emitted when selector execution begins'),
+  completed: z.tuple([z.any().describe('The result data')]).describe('Emitted when selector execution finishes'),
+  failed: z.tuple([z.any().describe('The error')]).describe('Emitted when selector execution fails'),
+}).describe('Base selector events')
+
 // Endpoint schemas
 export const EndpointStateSchema = HelperStateSchema.extend({
   mounted: z.boolean().default(false).describe('Whether the endpoint is mounted on a server'),
@@ -230,12 +261,22 @@ export function describeEventsSchema(
       // The event value is a tuple schema — its items describe positional args
       const items = eventProp?.prefixItems || eventProp?.items
       if (Array.isArray(items)) {
-        items.forEach((item: any, index: number) => {
-          args[`arg${index}`] = {
-            type: item.type || 'any',
-            description: item.description || ''
+        if (items.length === 1 && items[0].type === 'object' && items[0].properties) {
+          // Single object payload — expand its properties as named arguments
+          for (const [propName, propSchema] of Object.entries(items[0].properties) as [string, any][]) {
+            args[propName] = {
+              type: propSchema.enum ? propSchema.enum.map((v: any) => `'${v}'`).join(' | ') : (propSchema.type || 'any'),
+              description: propSchema.description || ''
+            }
           }
-        })
+        } else {
+          items.forEach((item: any, index: number) => {
+            args[`arg${index}`] = {
+              type: item.type || 'any',
+              description: item.description || ''
+            }
+          })
+        }
       }
 
       result[eventName] = {

package/src/selector.ts

@@ -0,0 +1,282 @@
+import { Helper } from './helper.js'
+import type { Container, ContainerContext } from './container.js'
+import { Registry } from './registry.js'
+import { SelectorStateSchema, SelectorOptionsSchema, SelectorEventsSchema, type SelectorRunResult } from './schemas/base.js'
+import { z } from 'zod'
+import { join } from 'path'
+import { graftModule, isNativeHelperClass } from './graft.js'
+
+export type { SelectorRunResult }
+
+export type SelectorState = z.infer<typeof SelectorStateSchema>
+export type SelectorOptions = z.infer<typeof SelectorOptionsSchema>
+
+export interface AvailableSelectors {}
+
+export type SelectorFactory = <T extends keyof AvailableSelectors>(
+	key: T,
+	options?: ConstructorParameters<AvailableSelectors[T]>[0]
+) => NonNullable<InstanceType<AvailableSelectors[T]>>
+
+export interface SelectorsInterface {
+	selectors: SelectorsRegistry
+	select: SelectorFactory
+}
+
+/**
+ * Type helper for module-augmentation of AvailableSelectors when using the
+ * module-based pattern.
+ *
+ * @example
+ * ```typescript
+ * declare module '@soederpop/luca' {
+ *   interface AvailableSelectors {
+ *     packageInfo: SimpleSelector<typeof argsSchema>
+ *   }
+ * }
+ * ```
+ */
+export type SimpleSelector<Schema extends z.ZodType = z.ZodType> = typeof Selector & {
+	argsSchema: Schema
+}
+
+/**
+ * A Selector is a helper that returns data. Where Commands perform actions,
+ * Selectors query and return structured results with built-in caching.
+ *
+ * Module authors export a `run(args, context)` function that returns data.
+ * The `select()` dispatch method wraps `run()` with cache check/store and
+ * returns `{ data, cached, cacheKey }`.
+ *
+ * Caching is on by default and keyed by `hashObject({ selectorName, args, gitSha })`.
+ * Export a `cacheKey(args, context)` function to customize, or set `cacheable = false`
+ * to disable.
+ *
+ * @example
+ * ```typescript
+ * // selectors/package-info.ts
+ * export const description = 'Returns parsed package.json data'
+ * export const argsSchema = z.object({ field: z.string().optional() })
+ *
+ * export function cacheKey(args, context) {
+ *   return context.container.git.sha
+ * }
+ *
+ * export async function run(args, context) {
+ *   const manifest = context.container.manifest
+ *   return args.field ? manifest[args.field] : manifest
+ * }
+ * ```
+ */
+export class Selector<
+	T extends SelectorState = SelectorState,
+	K extends SelectorOptions = SelectorOptions
+> extends Helper<T, K> {
+	static override shortcut = 'selectors.base'
+	static override description = 'Base selector'
+	static override stateSchema = SelectorStateSchema
+	static override optionsSchema = SelectorOptionsSchema
+	static override eventsSchema = SelectorEventsSchema
+
+	static selectorDescription: string = ''
+	static argsSchema: z.ZodType = SelectorOptionsSchema
+	static cacheable: boolean = true
+
+	/** Self-register a Selector subclass from a static initialization block. */
+	static register: (SubClass: typeof Selector, id?: string) => typeof Selector
+
+	override get initialState(): T {
+		return ({ running: false } as unknown) as T
+	}
+
+	/**
+	 * The user-defined selector payload. Override this in module-based selectors
+	 * by exporting a `run` function.
+	 *
+	 * Receives validated args and the container context. Must return data.
+	 */
+	async run(_args: any, _context: ContainerContext): Promise<any> {
+		// override via grafted module export
+	}
+
+	/**
+	 * Compute the cache key for a given set of args.
+	 * Override by exporting a `cacheKey(args, context)` function in the module.
+	 *
+	 * Default: hashObject({ selectorName, args, gitSha })
+	 */
+	resolveCacheKey(args: any, _context: ContainerContext): string {
+		const name = (this.constructor as typeof Selector).shortcut || 'selector'
+		const gitSha = (this.container as any).git?.currentCommitSha ?? 'unknown'
+		return (this.container as any).utils.hashObject({ selectorName: name, args, gitSha })
+	}
+
+	/**
+	 * The public dispatch method. Checks cache, calls run(), stores result.
+	 *
+	 * @returns `{ data, cached, cacheKey }` — the result and cache metadata
+	 */
+	async select(args?: Record<string, any>): Promise<SelectorRunResult> {
+		const Cls = this.constructor as typeof Selector
+		const parsed = Cls.argsSchema.parse(args ?? {})
+		const resolvedCacheKey = this.resolveCacheKey(parsed, this.context)
+
+		// Cache check
+		if (Cls.cacheable) {
+			try {
+				const cache = this._getCache()
+				if (await cache.has(resolvedCacheKey)) {
+					const data = await cache.get(resolvedCacheKey, true)
+					return { data, cached: true, cacheKey: resolvedCacheKey }
+				}
+			} catch {
+				// Cache miss or unavailable — proceed to run
+			}
+		}
+
+		// Run the selector
+		this.state.set('running' as any, true)
+		this.emit('started' as any)
+
+		let data: any
+		try {
+			data = await this.run(parsed, this.context)
+			this.state.set('running' as any, false)
+			this.state.set('lastRanAt' as any, Date.now())
+			this.emit('completed' as any, data)
+		} catch (err: any) {
+			this.state.set('running' as any, false)
+			this.emit('failed' as any, err)
+			throw err
+		}
+
+		// Cache store
+		if (Cls.cacheable) {
+			try {
+				await this._getCache().set(resolvedCacheKey, data)
+			} catch {
+				// Cache write failure is non-fatal
+			}
+		}
+
+		return { data, cached: false, cacheKey: resolvedCacheKey }
+	}
+
+	/** Lazily access diskCache. */
+	private _getCache(): any {
+		return (this.container as any).feature('diskCache', { enable: true })
+	}
+
+	static attach(container: Container<any> & SelectorsInterface) {
+		container.selectors = selectors
+
+		Object.assign(container, {
+			select<T extends keyof AvailableSelectors>(
+				id: T,
+				options?: ConstructorParameters<AvailableSelectors[T]>[0]
+			): NonNullable<InstanceType<AvailableSelectors[T]>> {
+				const BaseClass = selectors.lookup(id as string) as any
+
+				return container.createHelperInstance({
+					cache: selectorHelperCache,
+					type: 'selector',
+					id: String(id),
+					BaseClass,
+					options,
+					fallbackName: String(id),
+				}) as NonNullable<InstanceType<AvailableSelectors[T]>>
+			},
+		})
+
+		container.registerHelperType('selectors', 'select')
+		return container
+	}
+}
+
+export class SelectorsRegistry extends Registry<Selector<any>> {
+	override scope = 'selectors'
+	override baseClass = Selector as any
+
+	/**
+	 * Discover and register selectors from a directory.
+	 * Detection order:
+	 *   1. Default export is a class extending Selector -> register directly
+	 *   2. Module exports a `run` function -> graft as SimpleSelector
+	 */
+	async discover(options: { directory: string }) {
+		const { Glob } = globalThis.Bun || (await import('bun'))
+		const glob = new Glob('*.ts')
+
+		for await (const file of glob.scan({ cwd: options.directory })) {
+			if (file === 'index.ts') continue
+
+			const name = file.replace(/\.ts$/, '')
+			if (this.has(name)) continue
+
+			const mod = await import(join(options.directory, file))
+
+			// 1. Class-based: default export extends Selector
+			if (isNativeHelperClass(mod.default, Selector)) {
+				const ExportedClass = mod.default
+				if (!ExportedClass.shortcut || ExportedClass.shortcut === 'selectors.base') {
+					ExportedClass.shortcut = `selectors.${name}`
+				}
+				this.register(name, ExportedClass)
+				continue
+			}
+
+			const selectorModule = mod.default || mod
+
+			// 2. Module-based with `run` export
+			if (typeof selectorModule.run === 'function') {
+				const Grafted = graftModule(Selector as any, selectorModule, name, 'selectors')
+				this.register(name, Grafted as any)
+			}
+		}
+	}
+}
+
+export const selectors = new SelectorsRegistry()
+export const selectorHelperCache = new Map()
+
+/**
+ * Self-register a Selector subclass from a static initialization block.
+ *
+ * @example
+ * ```typescript
+ * export class PackageInfoSelector extends Selector {
+ *   static override description = 'Returns parsed package.json data'
+ *   static { Selector.register(this, 'packageInfo') }
+ *
+ *   override async run(args, context) { return context.container.manifest }
+ * }
+ * ```
+ */
+Selector.register = function registerSelector(
+	SubClass: typeof Selector,
+	id?: string,
+) {
+	const registryId = id ?? (SubClass.name
+		? SubClass.name[0]!.toLowerCase() + SubClass.name.slice(1).replace(/Selector$/, '')
+		: `selector_${Date.now()}`)
+
+	if (!Object.getOwnPropertyDescriptor(SubClass, 'shortcut')?.value ||
+		(SubClass as any).shortcut === 'selectors.base') {
+		;(SubClass as any).shortcut = `selectors.${registryId}`
+	}
+
+	selectors.register(registryId, SubClass as any)
+
+	if (!Object.getOwnPropertyDescriptor(SubClass, 'attach')) {
+		;(SubClass as any).attach = (container: any) => {
+			selectors.register(registryId, SubClass as any)
+			return container
+		}
+	}
+
+	return SubClass
+}
+
+export { graftModule, isNativeHelperClass } from './graft.js'
+
+export default Selector

package/src/server.ts

@@ -91,6 +91,7 @@ export class Server<T extends ServerState = ServerState, K extends ServerOptions
       return !!this.state.get('stopped')
     }
 
+    /** The port this server will bind to. Reads from state first (set by start() or configure()), then constructor options, then defaults to 3000. */
     get port() {
       return this.state.get('port') || this.options.port || 3000
     }
@@ -105,11 +106,21 @@ export class Server<T extends ServerState = ServerState, K extends ServerOptions
       return this
     }
 
+    /**
+     * Start the server. Runtime options override constructor options and update state
+     * so that `server.port` always reflects the actual listening port.
+     *
+     * @param options - Optional runtime overrides for port and host
+     */
     async start(options?: StartOptions) {
       if(this.isListening) {
         return this
       }
 
+      if (options?.port) {
+        this.state.set('port', options.port)
+      }
+
       this.state.set('listening', true)
 
       return this

package/src/servers/express.ts

@@ -4,7 +4,7 @@ import cors from 'cors'
 import { z } from 'zod'
 import { ServerStateSchema, ServerOptionsSchema } from '../schemas/base.js'
 import { type StartOptions, Server, type ServerState } from '../server.js'
-import { Endpoint, type EndpointModule } from '../endpoint.js'
+import { Endpoint, type EndpointModule, warnUnknownExports } from '../endpoint.js'
 
 declare module '../server' {
   interface AvailableServers {
@@ -88,26 +88,34 @@ export class ExpressServer<T extends ServerState = ServerState, K extends Expres
       
       // @ts-ignore-next-line
       const server : Server = this
-      this.hooks.create(app, server)
-
       this._app = this.hooks.create(app, server) || app
 
       return app
     }
   
+    /**
+     * Start the Express HTTP server. A runtime `port` overrides the constructor
+     * option and is written to state so `server.port` always reflects reality.
+     *
+     * @param options - Optional runtime overrides for port and host
+     */
     override async start(options?: StartOptions) {
       if (this.isListening) {
         return this
       }
 
-      options = {
-        port: this.options.port || 3000,
-        host: this.options.host || '0.0.0.0',
-        ...options || {}
+      // Apply runtime port to state so this.port reflects the override
+      if (options?.port) {
+        this.state.set('port', options.port)
+      }
+
+      const startOptions = {
+        port: this.port,
+        host: options?.host || this.options.host || '0.0.0.0',
       }
 
       // @ts-ignore-next-line
-      await this.hooks.beforeStart(options, this)
+      await this.hooks.beforeStart(startOptions, this)
 
       // SPA history fallback: serve index.html for unmatched GET routes
       if (this.options.historyFallback && this.options.static) {
@@ -118,12 +126,12 @@ export class ExpressServer<T extends ServerState = ServerState, K extends Expres
       }
 
       await new Promise((res) => {
-        this._listener = this.app.listen(options?.port!, options?.host!, () => {
+        this._listener = this.app.listen(startOptions.port, startOptions.host, () => {
           this.state.set('listening', true)
           res(null)
         })
       })
-      
+
       return this
     }
 
@@ -169,17 +177,24 @@ export class ExpressServer<T extends ServerState = ServerState, K extends Expres
     }
 
     async useEndpoints(dir: string): Promise<this> {
-      const glob = new Bun.Glob('**/*.ts')
+      const { Glob } = globalThis.Bun || (await import('bun'))
+      const glob = new Glob('**/*.ts')
+
+      // Use the helpers feature's VM-aware loader so endpoints can resolve
+      // packages like zod and @soederpop/luca even from the compiled binary
+      const helpers = this.container.feature('helpers') as any
 
       for await (const file of glob.scan({ cwd: dir, absolute: true })) {
         try {
-          const mod = await import(file)
+          const mod = await helpers.loadModuleExports(file)
           const endpointModule: EndpointModule = mod.default || mod
 
           if (!endpointModule.path) {
             continue
           }
 
+          warnUnknownExports(mod, file)
+
           const endpoint = new Endpoint(
             { path: endpointModule.path, filePath: file },
             this.container.context

package/src/servers/socket.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { ServerStateSchema, ServerOptionsSchema } from '../schemas/base.js'
+import { ServerStateSchema, ServerOptionsSchema, ServerEventsSchema } from '../schemas/base.js'
 import { type StartOptions, Server, type ServerState } from '../server.js';
 import { WebSocketServer as BaseServer } from 'ws'
 
@@ -10,16 +10,24 @@ declare module '../server' {
 }
 
 export const SocketServerOptionsSchema = ServerOptionsSchema.extend({
-  json: z.boolean().optional().describe('Whether to automatically JSON parse/stringify messages'),
+  json: z.boolean().optional().describe('When enabled, incoming messages are automatically JSON-parsed before emitting the message event, and outgoing send/broadcast calls JSON-stringify the payload'),
 })
 export type SocketServerOptions = z.infer<typeof SocketServerOptionsSchema>
 
+export const SocketServerEventsSchema = ServerEventsSchema.extend({
+  connection: z.tuple([z.any().describe('The raw WebSocket client instance from the ws library')]).describe('Fires when a new client connects'),
+  message: z.tuple([z.any().describe('The message data (JSON-parsed object when json option is enabled, raw Buffer/string otherwise)'), z.any().describe('The WebSocket client that sent the message — use with server.send(ws, data) to reply')]).describe('Fires when a message is received from a client. Handler signature: (data, ws)'),
+}).describe('WebSocket server events')
+
 /**
  * WebSocket server built on the `ws` library with optional JSON message framing.
  *
  * Manages WebSocket connections, tracks connected clients, and bridges
- * messages to Luca's event bus. When `json` mode is enabled, messages
- * are automatically parsed and stringified.
+ * messages to Luca's event bus. When `json` mode is enabled, incoming
+ * messages are automatically JSON-parsed (with `.toString()` for Buffer data)
+ * and outgoing messages via `send()` / `broadcast()` are JSON-stringified.
+ * When `json` mode is disabled, raw message data is emitted as-is and
+ * `send()` / `broadcast()` still JSON-stringify for safety.
  *
  * @extends Server
  *
@@ -28,7 +36,7 @@ export type SocketServerOptions = z.infer<typeof SocketServerOptionsSchema>
  * const ws = container.server('websocket', { json: true })
  * await ws.start({ port: 8080 })
  *
- * ws.on('message', (client, data) => {
+ * ws.on('message', (data, client) => {
  *   console.log('Received:', data)
  *   ws.broadcast({ echo: data })
  * })
@@ -38,6 +46,7 @@ export class WebsocketServer<T extends ServerState = ServerState, K extends Sock
     static override shortcut = 'servers.websocket' as const
     static override stateSchema = ServerStateSchema
     static override optionsSchema = SocketServerOptionsSchema
+    static override eventsSchema = SocketServerEventsSchema
 
     static { Server.register(this, 'websocket') }
     
@@ -68,19 +77,43 @@ export class WebsocketServer<T extends ServerState = ServerState, K extends Sock
       return this
     }
 
+    /**
+     * Start the WebSocket server. A runtime `port` overrides the constructor
+     * option and is written to state before the underlying `ws.Server` is created,
+     * so the server binds to the correct port.
+     *
+     * @param options - Optional runtime overrides for port and host
+     */
     override async start(options?: StartOptions) {
-      if(!this.isConfigured) {
+      if (this.isListening) {
+        return this
+      }
+
+      // Apply runtime port to state before configure/wss touches it
+      if (options?.port) {
+        this.state.set('port', options.port)
+        // Reset cached wss so it rebinds to the new port
+        this._wss = undefined
+      }
+
+      if(!this.isConfigured || options?.port) {
         await this.configure()
       }
-      
+
       const { wss } = this
       
       wss.on('connection', (ws) => {
         this.connections.add(ws)
         this.emit('connection', ws)
-        
-        ws.on('message', (data) => {
-          this.emit('message', data, ws)  
+
+        ws.on('message', (raw) => {
+          let data: any = raw
+          if (this.options.json) {
+            try {
+              data = JSON.parse(typeof raw === 'string' ? raw : raw.toString())
+            } catch {}
+          }
+          this.emit('message', data, ws)
         })
       })
       
@@ -127,8 +160,9 @@ export class WebsocketServer<T extends ServerState = ServerState, K extends Sock
       return this
     }
     
+    /** The port this server will bind to. Defaults to 8081 if not set via constructor options or start(). */
     override get port() {
-      return this.state.get('port') || this.options.port || 8081 
+      return this.state.get('port') || this.options.port || 8081
     }
 }
 

package/src/web/clients/socket.ts

@@ -1,5 +1,7 @@
 import Websocket from 'isomorphic-ws'
-import { Client, WebSocketClient, type WebSocketClientState, type WebSocketClientOptions } from '../../client'
+import { Client } from '../../client'
+import { WebSocketClient, type WebSocketClientState, type WebSocketClientOptions } from '../../clients/websocket'
+import { WebSocketClientEventsSchema } from '../../schemas/base.js'
 
 /**
  * Web-specific WebSocket client implementation using isomorphic-ws.
@@ -11,6 +13,7 @@ export class SocketClient<T extends WebSocketClientState = WebSocketClientState,
   declare ws: Websocket | WebSocket
 
   static override shortcut = 'clients.websocket' as const
+  static override eventsSchema = WebSocketClientEventsSchema
 
   static { Client.register(this, 'websocket') }
 

package/src/web/container.ts

@@ -1,6 +1,7 @@
 export * from '../container.js'
 import { Container } from '../container.js'
-import { Client, RestClient } from '../client.js'
+import { Client } from '../client.js'
+import { RestClient } from '../clients/rest.js'
 import { SocketClient } from './clients/socket.js'
 import type { AvailableFeatures } from '../feature.js'
 import type { ContainerState, ContainerArgv } from '../container.js' 

package/src/web/features/network.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { Feature } from "../feature.js";
 import type { ContainerContext } from "../container.js";
 
@@ -9,6 +9,11 @@ export const NetworkStateSchema = FeatureStateSchema.extend({
 
 export const NetworkOptionsSchema = FeatureOptionsSchema.extend({})
 
+export const NetworkEventsSchema = FeatureEventsSchema.extend({
+  online: z.tuple([]).describe('Fires when the browser regains network connectivity'),
+  offline: z.tuple([]).describe('Fires when the browser loses network connectivity'),
+}).describe('Network events')
+
 export type NetworkState = z.infer<typeof NetworkStateSchema>
 export type NetworkOptions = z.infer<typeof NetworkOptionsSchema>
 
@@ -37,6 +42,7 @@ export class Network<
 > extends Feature<T, K> {
   static override stateSchema = NetworkStateSchema
   static override optionsSchema = NetworkOptionsSchema
+  static override eventsSchema = NetworkEventsSchema
   static override shortcut = "features.network" as const
 
   static { Feature.register(this as any, 'network') }