luca 2.0.0 → 3.0.0

package/src/scaffolds/template.ts

@@ -0,0 +1,46 @@
+import { scaffolds } from './generated.js'
+
+/** Convert a string to PascalCase */
+export function toPascalCase(str: string): string {
+	return str
+		.replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ''))
+		.replace(/^(.)/, (_, c) => c.toUpperCase())
+}
+
+/** Convert a string to camelCase */
+export function toCamelCase(str: string): string {
+	const pascal = toPascalCase(str)
+	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
+	for (const [key, value] of Object.entries(vars)) {
+		result = result.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value)
+	}
+	return result
+}
+
+/** Generate scaffolded code for a given helper type */
+export function generateScaffold(type: string, name: string, description?: string): string | null {
+	const scaffold = scaffolds[type]
+	if (!scaffold?.full) return null
+
+	const vars = {
+		PascalName: toPascalCase(name),
+		camelName: toCamelCase(name),
+		kebabName: toKebabCase(name),
+		description: description || `A ${type} that does something useful`,
+	}
+
+	return applyTemplate(scaffold.full, vars)
+}

package/src/schemas/base.ts

@@ -0,0 +1,296 @@
+import { z } from 'zod'
+
+// Base helper schemas — looseObject allows additional properties so subclass
+// state types can structurally extend the base via z.infer<>
+export const HelperStateSchema = z.looseObject({}).describe('Base state for all helpers')
+
+export const HelperOptionsSchema = z.object({
+  name: z.string().optional().describe('Optional name identifier for this helper instance'),
+  _cacheKey: z.string().optional().describe('Internal cache key used for instance deduplication'),
+}).describe('Base options for all helpers')
+
+// Type inference utilities
+export type InferState<T extends z.ZodType> = z.infer<T>
+export type InferOptions<T extends z.ZodType> = z.infer<T>
+
+/**
+ * Infer an EventMap from an events schema where each key is an event name
+ * and each value is a z.tuple() describing the listener arguments.
+ *
+ * e.g. z.object({ ready: z.tuple([]), message: z.tuple([z.string()]) })
+ *   => { ready: [], message: [string] }
+ */
+export type InferEvents<T extends z.ZodType> = z.infer<T> extends infer E
+  ? { [K in keyof E]: E[K] extends any[] ? E[K] : any[] }
+  : Record<string, any[]>
+
+// Schema composition helpers
+export const createHelperSchemas = <
+  StateSchema extends z.ZodType,
+  OptionsSchema extends z.ZodType
+>(
+  stateSchema: StateSchema,
+  optionsSchema: OptionsSchema
+) => ({
+  state: stateSchema,
+  options: optionsSchema,
+  types: {} as {
+    State: InferState<StateSchema>
+    Options: InferOptions<OptionsSchema>
+  }
+})
+
+// Container state schema
+export const ContainerStateSchema = z.object({
+  started: z.boolean().default(false).describe('Whether the container has been started'),
+  enabledFeatures: z.array(z.string()).describe('List of currently enabled feature shortcut IDs'),
+  registries: z.array(z.string()).describe('Names of attached registries (e.g. features, clients, servers)'),
+  factories: z.array(z.string()).describe('Names of available factory methods (e.g. feature, client, server)'),
+}).describe('Core container state')
+
+// Base schemas for common types
+export const FeatureStateSchema = HelperStateSchema.extend({
+  enabled: z.boolean().default(false).describe('Whether this feature is currently enabled'),
+}).describe('Base feature state with enabled flag')
+
+export const FeatureOptionsSchema = HelperOptionsSchema.extend({
+  cached: z.boolean().optional().describe('Whether to cache this feature instance'),
+  enable: z.boolean().optional().describe('Whether to automatically enable the feature on creation'),
+}).describe('Base feature options with cached and enable flags')
+
+export const ClientStateSchema = HelperStateSchema.extend({
+  connected: z.boolean().default(false).describe('Whether the client is currently connected'),
+}).describe('Base client state with connection status')
+
+export const ClientOptionsSchema = HelperOptionsSchema.extend({
+  baseURL: z.string().optional().describe('Base URL for the client connection'),
+  json: z.boolean().optional().describe('Whether to automatically parse responses as JSON'),
+}).describe('Base client options with connection settings')
+
+export const ServerStateSchema = HelperStateSchema.extend({
+  port: z.number().optional().describe('The port the server is bound to'),
+  listening: z.boolean().default(false).describe('Whether the server is actively listening for connections'),
+  configured: z.boolean().default(false).describe('Whether the server has been configured'),
+  stopped: z.boolean().default(false).describe('Whether the server has been stopped'),
+}).describe('Base server state with port and status information')
+
+export const ServerOptionsSchema = HelperOptionsSchema.extend({
+  port: z.number().positive().optional().describe('Port number to listen on'),
+  host: z.string().optional().describe('Hostname or IP address to bind to'),
+}).describe('Base server options with port and host settings')
+
+// Events schemas — each key is an event name, value is z.tuple() of listener args
+export const HelperEventsSchema = z.object({
+  stateChange: z.tuple([z.any().describe('The current state object')]),
+}).describe('Base events for all helpers')
+
+export const FeatureEventsSchema = HelperEventsSchema.extend({
+  enabled: z.tuple([]).describe('Emitted when the feature is enabled'),
+}).describe('Base feature events')
+
+export const ClientEventsSchema = HelperEventsSchema.extend({
+  failure: z.tuple([z.any().describe('The error object')]).describe('Emitted when a request fails'),
+}).describe('Base client events')
+
+// WebSocket client schemas
+export const WebSocketClientStateSchema = ClientStateSchema.extend({
+  connectionError: z.any().optional().describe('The last connection error, if any'),
+  reconnectAttempts: z.number().default(0).describe('Number of reconnection attempts made'),
+}).describe('WebSocket client state with connection error and reconnect tracking')
+
+export const WebSocketClientOptionsSchema = ClientOptionsSchema.extend({
+  reconnect: z.boolean().optional().describe('Whether to automatically reconnect on disconnection'),
+  reconnectInterval: z.number().optional().describe('Base interval in milliseconds between reconnection attempts'),
+  maxReconnectAttempts: z.number().optional().describe('Maximum number of reconnection attempts before giving up'),
+}).describe('WebSocket client options with reconnection settings')
+
+export const WebSocketClientEventsSchema = ClientEventsSchema.extend({
+  message: z.tuple([z.any().describe('The parsed message data')]).describe('Emitted when a message is received'),
+  open: z.tuple([]).describe('Emitted when the WebSocket connection is established'),
+  close: z.tuple([z.number().optional().describe('Close code'), z.string().optional().describe('Close reason')]).describe('Emitted when the WebSocket connection is closed'),
+  error: z.tuple([z.any().describe('The error')]).describe('Emitted when a WebSocket error occurs'),
+  reconnecting: z.tuple([z.number().describe('Attempt number')]).describe('Emitted when attempting to reconnect'),
+}).describe('WebSocket client events')
+
+// GraphQL client schemas
+export const GraphClientOptionsSchema = ClientOptionsSchema.extend({
+  endpoint: z.string().optional().describe('The GraphQL endpoint path, defaults to /graphql'),
+}).describe('GraphQL client options')
+
+export const GraphClientEventsSchema = ClientEventsSchema.extend({
+  graphqlError: z.tuple([z.array(z.any()).describe('Array of GraphQL errors')]).describe('Emitted when GraphQL-level errors are present in the response'),
+}).describe('GraphQL client events')
+
+export const ServerEventsSchema = HelperEventsSchema.extend({}).describe('Base server events')
+
+// MCP Server schemas
+export const MCPServerOptionsSchema = ServerOptionsSchema.extend({
+  transport: z.enum(['stdio', 'http']).optional().describe('Transport type for MCP communication'),
+  serverName: z.string().optional().describe('Server name reported to MCP clients'),
+  serverVersion: z.string().optional().describe('Server version reported to MCP clients'),
+  mcpCompat: z.enum(['standard', 'codex']).optional().describe('HTTP compatibility profile for MCP clients'),
+  stdioCompat: z.enum(['standard', 'codex', 'auto']).optional().describe('Stdio framing compatibility profile for MCP clients'),
+}).describe('MCP server options')
+
+export const MCPServerStateSchema = ServerStateSchema.extend({
+  transport: z.string().optional().describe('Active transport type'),
+  toolCount: z.number().default(0).describe('Number of registered tools'),
+  resourceCount: z.number().default(0).describe('Number of registered resources'),
+  promptCount: z.number().default(0).describe('Number of registered prompts'),
+}).describe('MCP server state with tool/resource/prompt counts')
+
+export const MCPServerEventsSchema = ServerEventsSchema.extend({
+  toolRegistered: z.tuple([z.string().describe('Tool name')]).describe('Emitted when a tool is registered'),
+  resourceRegistered: z.tuple([z.string().describe('Resource URI')]).describe('Emitted when a resource is registered'),
+  promptRegistered: z.tuple([z.string().describe('Prompt name')]).describe('Emitted when a prompt is registered'),
+  toolCalled: z.tuple([z.string().describe('Tool name'), z.any().describe('Arguments')]).describe('Emitted when a tool is called'),
+}).describe('MCP server events')
+
+// Command schemas
+export const CommandStateSchema = HelperStateSchema.extend({
+  running: z.boolean().default(false).describe('Whether the command is currently executing'),
+  exitCode: z.number().optional().describe('Exit code after command finishes'),
+}).describe('Base command state')
+
+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'),
+  path: z.string().default('').describe('The URL path this endpoint is served from'),
+  methods: z.array(z.string()).default([]).describe('HTTP methods this endpoint handles'),
+  requestCount: z.number().default(0).describe('Total number of requests handled'),
+}).describe('Base endpoint state')
+
+export const EndpointOptionsSchema = HelperOptionsSchema.extend({
+  path: z.string().describe('The URL path this endpoint is served from'),
+  filePath: z.string().optional().describe('Absolute path to the endpoint source file'),
+}).describe('Base endpoint options')
+
+export const EndpointEventsSchema = HelperEventsSchema.extend({
+  loaded: z.tuple([z.any().describe('The loaded endpoint module')]).describe('Emitted when the endpoint module is loaded'),
+  mounted: z.tuple([z.string().describe('The path')]).describe('Emitted when the endpoint is mounted on a server'),
+  request: z.tuple([z.string().describe('HTTP method'), z.string().describe('Path'), z.any().describe('Parameters')]).describe('Emitted on every request'),
+  error: z.tuple([z.any().describe('The error object')]).describe('Emitted when a request handler throws'),
+}).describe('Base endpoint events')
+
+/**
+ * Converts a ZodObject into an introspection-friendly record.
+ * Uses Zod v4's native toJSONSchema() and transforms properties
+ * into { fieldName: { type, description } } for the introspection system.
+ */
+export function describeZodShape(schema: z.ZodType): Record<string, { type: string, description: string }> {
+  try {
+    const jsonSchema = (schema as any).toJSONSchema()
+    const properties = jsonSchema?.properties || {}
+    const result: Record<string, { type: string, description: string }> = {}
+
+    for (const [key, prop] of Object.entries(properties) as [string, any][]) {
+      result[key] = {
+        type: prop.type || 'any',
+        description: prop.description || ''
+      }
+    }
+
+    return result
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Converts an events ZodObject schema into introspection-friendly EventIntrospection records.
+ *
+ * Each top-level key is an event name, and its value should be a z.tuple() describing
+ * the positional arguments passed to listeners.
+ *
+ * Merges with existing build-time event data (e.g. descriptions from AST scanning)
+ * while adding argument type information from the Zod schema.
+ */
+export function describeEventsSchema(
+  schema: z.ZodType,
+  existing: Record<string, { name: string, description: string, arguments: Record<string, { type: string, description: string }> }> = {}
+): Record<string, { name: string, description: string, arguments: Record<string, { type: string, description: string }> }> {
+  try {
+    const jsonSchema = (schema as any).toJSONSchema()
+    const properties = jsonSchema?.properties || {}
+    const result: Record<string, { name: string, description: string, arguments: Record<string, { type: string, description: string }> }> = { ...existing }
+
+    for (const [eventName, eventProp] of Object.entries(properties) as [string, any][]) {
+      const args: Record<string, { type: string, description: string }> = {}
+
+      // The event value is a tuple schema — its items describe positional args
+      const items = eventProp?.prefixItems || eventProp?.items
+      if (Array.isArray(items)) {
+        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] = {
+        name: eventName,
+        description: eventProp.description || existing[eventName]?.description || `Event: ${eventName}`,
+        arguments: {
+          ...(existing[eventName]?.arguments || {}),
+          ...args
+        }
+      }
+    }
+
+    return result
+  } catch {
+    return existing
+  }
+}

package/src/selector.ts

@@ -0,0 +1,352 @@
+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 as any)
+		this.emit('started' as any)
+
+		let data: any
+		try {
+			data = await this.run(parsed, this.context)
+			this.state.set('running' as any, false as any)
+			this.state.set('lastRanAt' as any, Date.now() as any)
+			this.emit('completed' as any, data)
+		} catch (err: any) {
+			this.state.set('running' as any, false as any)
+			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
+
+	/**
+	 * Convert all registered selectors into a `{ schemas, handlers }` object
+	 * compatible with `assistant.use()`.
+	 *
+	 * Each selector becomes a tool whose parameters come from the selector's
+	 * `argsSchema` (with internal fields stripped) and whose handler dispatches
+	 * the selector and returns the data directly (cache metadata is not exposed).
+	 *
+	 * @param container - The container used to instantiate and run selectors
+	 * @param options - Optional filter/transform options
+	 * @param options.include - Only include these selector names (default: all)
+	 * @param options.exclude - Exclude these selector names (default: none)
+	 * @param options.prefix - Prefix tool names (e.g. 'sel_' → 'sel_packageInfo')
+	 */
+	toTools(
+		container: Container<any> & SelectorsInterface,
+		options?: { include?: string[], exclude?: string[], prefix?: string },
+	): { schemas: Record<string, z.ZodType>, handlers: Record<string, Function> } {
+		const schemas: Record<string, z.ZodType> = {}
+		const handlers: Record<string, Function> = {}
+		const prefix = options?.prefix ?? ''
+		const includeSet = options?.include ? new Set(options.include) : null
+		const excludeSet = new Set(options?.exclude ?? [])
+
+		// Internal fields from HelperOptionsSchema and SelectorOptionsSchema
+		const internalFields = ['name', '_cacheKey', 'dispatchSource']
+
+		for (const name of this.available) {
+			if (excludeSet.has(name)) continue
+			if (includeSet && !includeSet.has(name)) continue
+
+			const Sel = this.lookup(name) as typeof Selector
+			const rawSchema = Sel.argsSchema
+			const description = Sel.selectorDescription || Sel.description || name
+
+			let toolSchema: z.ZodType
+			try {
+				const shape = typeof (rawSchema as any)?._def?.shape === 'function'
+					? (rawSchema as any)._def.shape()
+					: (rawSchema as any)?._def?.shape
+
+				if (shape) {
+					const cleanShape: Record<string, z.ZodType> = {}
+					for (const [key, val] of Object.entries(shape)) {
+						if (internalFields.includes(key)) continue
+						cleanShape[key] = val as z.ZodType
+					}
+
+					toolSchema = Object.keys(cleanShape).length > 0
+						? z.object(cleanShape).describe(description)
+						: z.object({}).describe(description)
+				} else {
+					toolSchema = z.object({}).describe(description)
+				}
+			} catch {
+				toolSchema = z.object({}).describe(description)
+			}
+
+			const toolName = `${prefix}${name}`
+			schemas[toolName] = toolSchema
+			handlers[toolName] = async (args: Record<string, any>) => {
+				const sel = (container.select as any)(name)
+				const result = await sel.select(args ?? {})
+				return result.data
+			}
+		}
+
+		return { schemas, handlers }
+	}
+
+	/**
+	 * 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