@soederpop/luca 0.0.5 → 0.0.7

package/docs/scaffolds/endpoint.md

@@ -18,12 +18,14 @@ Run `luca serve` and they're automatically discovered and mounted.
 
 ## Imports
 
-```ts
-import { z } from 'zod'
-import type { EndpointContext } from '@soederpop/luca'
-```
+Endpoints are lightweight — just exports and handler functions. No imports are required.
+
+If your project has `@soederpop/luca` as an npm dependency, you can import `z` from `zod` and `EndpointContext` from `@soederpop/luca` for type safety. Otherwise, use `any` types — the framework handles validation and context injection for you.
 
-That's it. Endpoints are lightweight — just exports and functions.
+Access framework capabilities through the `ctx` parameter:
+- `ctx.container.feature('fs')` for file operations
+- `ctx.container.feature('yaml')` for YAML parsing
+- `ctx.container.feature('sqlite')` for database access
 
 ## Required Exports
 
@@ -37,16 +39,16 @@ export const tags = ['{{camelName}}']
 
 ## Handler Functions
 
-Export named functions for each HTTP method you support. Each receives validated parameters and an `EndpointContext`:
+Export named functions for each HTTP method you support. Each receives validated parameters and a context object:
 
 ```ts
-export async function get(params: any, ctx: EndpointContext) {
+export async function get(params: any, ctx: any) {
   const fs = ctx.container.feature('fs')
   // Your logic here
   return { message: 'ok' }
 }
 
-export async function post(params: z.infer<typeof postSchema>, ctx: EndpointContext) {
+export async function post(params: any, ctx: any) {
   // Create something
   return { created: true }
 }
@@ -64,9 +66,11 @@ Return any object — it's automatically JSON-serialized as the response.
 
 ## Validation Schemas
 
-Export Zod schemas to validate parameters for each method. Name them `{method}Schema`:
+If `zod` is available (via `@soederpop/luca` dependency or `node_modules`), export Zod schemas to validate parameters for each method. Name them `{method}Schema`:
 
 ```ts
+import { z } from 'zod'
+
 export const getSchema = z.object({
   q: z.string().optional().describe('Search query'),
   limit: z.number().default(20).describe('Max results'),
@@ -78,7 +82,7 @@ export const postSchema = z.object({
 })
 ```
 
-Invalid requests automatically return 400 with Zod error details. Schemas also feed the auto-generated OpenAPI spec.
+Invalid requests automatically return 400 with Zod error details. Schemas also feed the auto-generated OpenAPI spec. If zod is not available, skip schema exports — the endpoint still works, you just lose automatic validation.
 
 ## Rate Limiting
 
@@ -94,42 +98,40 @@ export const postRateLimit = { maxRequests: 10, windowSeconds: 1 }
 
 ## Delete Handler
 
-`delete` is a reserved word in JS. Use an alias:
+`delete` is a reserved word in JS, so you can't use it as a function name directly. Use a named export alias:
 
 ```ts
-const del = async (params: any, ctx: EndpointContext) => {
+// Use a local name, then re-export as `delete`
+const del = async (params: any, ctx: any) => {
   return { deleted: true }
 }
 export { del as delete }
 ```
 
+You can also export `deleteSchema` and `deleteRateLimit` for validation and rate limiting on DELETE.
+
 ## Complete Example
 
-A CRUD endpoint for a resource:
+A CRUD endpoint for a resource (no external imports needed):
 
 ```ts
-import { z } from 'zod'
-import type { EndpointContext } from '@soederpop/luca'
-
 export const path = '/api/{{camelName}}'
 export const description = '{{description}}'
 export const tags = ['{{camelName}}']
 
-export const getSchema = z.object({
-  q: z.string().optional().describe('Search query'),
-})
-
-export async function get(params: z.infer<typeof getSchema>, ctx: EndpointContext) {
+export async function get(params: any, ctx: any) {
   return { items: [], total: 0 }
 }
 
-export const postSchema = z.object({
-  name: z.string().min(1).describe('Item name'),
-})
-
-export async function post(params: z.infer<typeof postSchema>, ctx: EndpointContext) {
+export async function post(params: any, ctx: any) {
   return { item: { id: '1', ...params }, message: 'Created' }
 }
+
+const del = async (params: any, ctx: any) => {
+  const { id } = ctx.params
+  return { message: `Deleted ${id}` }
+}
+export { del as delete }
 ```
 
 ## Dynamic Route Example
@@ -138,28 +140,21 @@ For routes with URL parameters, create a nested file:
 
 ```ts
 // endpoints/{{camelName}}/[id].ts
-import { z } from 'zod'
-import type { EndpointContext } from '@soederpop/luca'
-
 export const path = '/api/{{camelName}}/:id'
 export const description = 'Get, update, or delete a specific item'
 export const tags = ['{{camelName}}']
 
-export async function get(params: any, ctx: EndpointContext) {
+export async function get(params: any, ctx: any) {
   const { id } = ctx.params
   return { item: { id } }
 }
 
-export const putSchema = z.object({
-  name: z.string().min(1).optional().describe('Updated name'),
-})
-
-export async function put(params: z.infer<typeof putSchema>, ctx: EndpointContext) {
+export async function put(params: any, ctx: any) {
   const { id } = ctx.params
   return { item: { id, ...params }, message: 'Updated' }
 }
 
-const del = async (params: any, ctx: EndpointContext) => {
+const del = async (params: any, ctx: any) => {
   const { id } = ctx.params
   return { message: `Deleted ${id}` }
 }

package/docs/scaffolds/feature.md

@@ -12,12 +12,15 @@ When to build a feature:
 ```ts
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '@soederpop/luca'
-import { Feature, features } from '@soederpop/luca'
-import type { ContainerContext } from '@soederpop/luca'
+import { Feature } from '@soederpop/luca'
 ```
 
 These are the only imports your feature file needs from luca. If your feature wraps a third-party library, import it here too — feature implementations are the ONE place where direct library imports are allowed.
 
+The use of dynamic imports is encouraged here, only import libraries you need when the feature is used, and only when necessary in the lifecycle of the feature if it can be done.
+
+feature's have built in ways to check if their requirements are supported and can be enabled cautiously.
+
 ## Schemas
 
 Define the shape of your feature's state, options, and events using Zod. Every field must have a `.describe()` — this becomes the documentation.
@@ -45,11 +48,11 @@ export const {{PascalName}}EventsSchema = FeatureEventsSchema.extend({
 
 The class extends `Feature` with your state and options types. Static properties drive registration and introspection. Every public method needs a JSDoc block with `@param`, `@returns`, and `@example`.
 
+Running `luca introspect` captures JSDoc blocks and Zod schemas and includes them in the description whenever somebody calls `container.features.describe('{{camelName}}')` or `luca describe {{camelName}}`.
+
 ```ts
 /**
  * {{description}}
- *
- * @example
  * ```typescript
  * const {{camelName}} = container.feature('{{camelName}}')
  * ```
@@ -61,17 +64,21 @@ export class {{PascalName}} extends Feature<{{PascalName}}State, {{PascalName}}O
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
   static override eventsSchema = {{PascalName}}EventsSchema
-  static override description = '{{description}}'
 
-  constructor(options: {{PascalName}}Options, context: ContainerContext) {
-    super(options, context)
-    // Initialize state, set up resources
-  }
+  static { Feature.register(this, '{{camelName}}') }
 
-  // Add your methods here. Every public method needs JSDoc.
+  /**
+   * Called after the feature is initialized. Use this for any setup logic
+   * instead of overriding the constructor.
+   */
+  async afterInitialize() {
+    // Set up initial state, start background tasks, etc.
+  }
 }
 ```
 
+**Important**: You almost never need to override the constructor. Use `afterInitialize()` for any setup logic — it runs after the feature is fully wired into the container and has access to `this.container`, `this.options`, `this.state`, etc.
+
 ## Module Augmentation
 
 This is what gives `container.feature('yourName')` TypeScript autocomplete. Without it, the feature works but TypeScript won't know about it.
@@ -86,10 +93,14 @@ declare module '@soederpop/luca' {
 
 ## Registration
 
-The last line of the file registers the feature in the global registry. This must happen at module level (not inside a function).
+Registration happens inside the class body using a static block. The default export is just the class itself.
 
 ```ts
-export default features.register('{{camelName}}', {{PascalName}})
+// Inside the class:
+static { Feature.register(this, '{{camelName}}') }
+
+// At module level:
+export default {{PascalName}}
 ```
 
 ## Complete Example
@@ -99,8 +110,7 @@ Here's a minimal but complete feature. This is what a real feature file looks li
 ```ts
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema } from '@soederpop/luca'
-import { Feature, features } from '@soederpop/luca'
-import type { ContainerContext } from '@soederpop/luca'
+import { Feature } from '@soederpop/luca'
 
 declare module '@soederpop/luca' {
   interface AvailableFeatures {
@@ -128,14 +138,14 @@ export class {{PascalName}} extends Feature<{{PascalName}}State, {{PascalName}}O
   static override shortcut = 'features.{{camelName}}' as const
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
-  static override description = '{{description}}'
+  static { Feature.register(this, '{{camelName}}') }
 
-  constructor(options: {{PascalName}}Options, context: ContainerContext) {
-    super(options, context)
+  async afterInitialize() {
+    // Setup logic goes here — not in the constructor
   }
 }
 
-export default features.register('{{camelName}}', {{PascalName}})
+export default {{PascalName}}
 ```
 
 ## Conventions

package/docs/scaffolds/selector.md

@@ -0,0 +1,91 @@
+# Building a Selector
+
+A selector returns data. Where commands perform actions, selectors query and return structured results with built-in caching. Selectors live in a project's `selectors/` folder and are automatically discovered.
+
+When to build a selector:
+- You need to query project data (package info, file listings, config values)
+- The result benefits from caching (keyed by git SHA or custom key)
+- You want the data available via `container.select('name')` or `luca select name`
+
+## Imports
+
+```ts
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+```
+
+## Args Schema
+
+Define the selector's input arguments with Zod.
+
+```ts
+export const argsSchema = z.object({
+  // Add your input arguments here.
+  // Example: field: z.string().optional().describe('Specific field to return'),
+})
+```
+
+## Description
+
+Export a description string for discoverability:
+
+```ts
+export const description = '{{description}}'
+```
+
+## Caching
+
+Selectors cache by default. The default cache key is `hashObject({ selectorName, args, gitSha })` — same args + same commit = cache hit.
+
+To customize the cache key:
+
+```ts
+export function cacheKey(args: z.infer<typeof argsSchema>, context: ContainerContext) {
+  return context.container.git.currentCommitSha
+}
+```
+
+To disable caching:
+
+```ts
+export const cacheable = false
+```
+
+## Handler
+
+Export a `run` function that returns data. It receives parsed args and the container context.
+
+```ts
+export async function run(args: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const { container } = context
+  // Query and return your data
+  return { /* your data */ }
+}
+```
+
+## Complete Example
+
+```ts
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+
+export const description = '{{description}}'
+
+export const argsSchema = z.object({})
+
+export async function run(args: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const { container } = context
+
+  // Return your data here
+  return {}
+}
+```
+
+## Conventions
+
+- **File location**: `selectors/{{kebabName}}.ts` in the project root. Discovered automatically.
+- **Naming**: kebab-case for filename. `luca select {{kebabName}}` maps to `selectors/{{kebabName}}.ts`.
+- **Use the container**: Never import `fs`, `path` directly. Use `container.feature('fs')`, `container.paths`.
+- **Return data**: The `run` function must return the data. It gets wrapped in `{ data, cached, cacheKey }` by the framework.
+- **Caching**: On by default. Override `cacheKey()` for custom invalidation, or set `cacheable = false` to skip.
+- **CLI**: `luca select {{kebabName}}` runs the selector and prints JSON. Use `--json` for data only, `--no-cache` to force fresh.

package/docs/scaffolds/server.md

@@ -11,9 +11,9 @@ When to build a server:
 
 ```ts
 import { z } from 'zod'
-import { Server, servers } from '@soederpop/luca'
+import { Server } from '@soederpop/luca'
 import { ServerStateSchema, ServerOptionsSchema, ServerEventsSchema } from '@soederpop/luca'
-import type { ContainerContext, NodeContainer } from '@soederpop/luca'
+import type { NodeContainer } from '@soederpop/luca'
 import type { ServersInterface } from '@soederpop/luca'
 ```
 
@@ -40,6 +40,8 @@ export const {{PascalName}}EventsSchema = ServerEventsSchema.extend({
 
 ## Class
 
+Running `luca introspect` captures JSDoc blocks and Zod schemas and includes them in the description whenever somebody calls `container.servers.describe('{{camelName}}')` or `luca describe {{camelName}}`.
+
 ```ts
 /**
  * {{description}}
@@ -57,7 +59,7 @@ export class {{PascalName}} extends Server<{{PascalName}}State, {{PascalName}}Op
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
   static override eventsSchema = {{PascalName}}EventsSchema
-  static override description = '{{description}}'
+  static { Server.register(this, '{{camelName}}') }
 
   static override attach(container: NodeContainer & ServersInterface) {
     return container
@@ -103,17 +105,23 @@ declare module '@soederpop/luca' {
 
 ## Registration
 
+Registration happens inside the class body using a static block. The default export is just the class itself.
+
 ```ts
-export default servers.register('{{camelName}}', {{PascalName}})
+// Inside the class:
+static { Server.register(this, '{{camelName}}') }
+
+// At module level:
+export default {{PascalName}}
 ```
 
 ## Complete Example
 
 ```ts
 import { z } from 'zod'
-import { Server, servers } from '@soederpop/luca'
+import { Server } from '@soederpop/luca'
 import { ServerStateSchema, ServerOptionsSchema, ServerEventsSchema } from '@soederpop/luca'
-import type { ContainerContext, NodeContainer } from '@soederpop/luca'
+import type { NodeContainer } from '@soederpop/luca'
 import type { ServersInterface } from '@soederpop/luca'
 
 declare module '@soederpop/luca' {
@@ -146,7 +154,7 @@ export class {{PascalName}} extends Server<{{PascalName}}State, {{PascalName}}Op
   static override stateSchema = {{PascalName}}StateSchema
   static override optionsSchema = {{PascalName}}OptionsSchema
   static override eventsSchema = {{PascalName}}EventsSchema
-  static override description = '{{description}}'
+  static { Server.register(this, '{{camelName}}') }
 
   static override attach(container: NodeContainer & ServersInterface) {
     return container
@@ -175,13 +183,14 @@ export class {{PascalName}} extends Server<{{PascalName}}State, {{PascalName}}Op
   }
 }
 
-export default servers.register('{{camelName}}', {{PascalName}})
+export default {{PascalName}}
 ```
 
 ## Conventions
 
 - **Lifecycle**: Implement `configure()`, `start()`, and `stop()`. Check guards (`isConfigured`, `isListening`, `isStopped`) at the top of each.
+- **Use `afterInitialize()`**: For any setup logic instead of overriding the constructor. Lifecycle methods (`configure`, `start`, `stop`) handle the server's runtime phases.
 - **State tracking**: Set `configured`, `listening`, `stopped`, and `port` on the state. This powers the introspection system.
 - **attach() is static**: It runs when the container first loads the server class. Use it for container-level setup if needed.
 - **Port from options**: Accept port via options schema and respect it in `start()`. Allow override via start options.
-- **JSDoc everything**: Every public method needs `@param`, `@returns`, `@example`.
+- **JSDoc everything**: Every public method needs `@param`, `@returns`, `@example`. Run `luca introspect` after changes to update generated docs.

package/docs/selectors.md

@@ -0,0 +1,115 @@
+# Selector System
+
+## Vision
+
+Commands perform actions. Selectors return data. Together they form a complete agent tool interface — pick which commands and selectors you need and you get free assistant tools. Agents only need to know the external APIs of features, servers, and clients already in the container (which can be learned from `luca describe`).
+
+## What Is a Selector?
+
+A Selector is a new helper type (like Feature, Client, Server, Command) that:
+
+- Extends `Helper` with a `select(options)` method that **returns data**
+- Lives in a `SelectorsRegistry`, queryable via `container.selectors`
+- Is instantiated via `container.selector('name', options)` factory
+- Supports **caching** via `diskCache` — many selector values don't change if git SHAs don't change, so SHA makes a great cache key
+- Is discoverable from a `selectors/` folder in projects, just like `commands/`
+- Supports both **class-based** and **module-based** (export a `select` function) patterns
+
+## Architecture — How It Maps to Existing Patterns
+
+The implementation follows the exact same pattern as `Command`:
+
+### Files to Create/Modify
+
+1. **`src/schemas/base.ts`** — Add `SelectorStateSchema`, `SelectorOptionsSchema`, `SelectorEventsSchema`
+2. **`src/selector.ts`** — New file mirroring `src/command.ts`:
+   - `Selector` class extending `Helper` with `select()` method
+   - `SelectorsRegistry` extending `Registry` with `discover()` support
+   - `selectors` singleton, `helperCache`, `Selector.register()`, `Selector.attach()`
+   - `AvailableSelectors` interface, `SelectorsInterface`, `SelectorFactory` type
+   - Module-based pattern: `SimpleSelector` type for graft compatibility
+3. **`src/node/container.ts`** — Import `Selector` + `SelectorsInterface`, add to `ClientsAndServersInterface`, wire `this.use(Selector)`
+4. **`src/node/features/helpers.ts`** — Add `selectors` to `registryMap` and `RegistryType`, add to `discoverAll()` iteration
+
+### Selector Base Class Shape
+
+```typescript
+class Selector<T, K> extends Helper<T, K> {
+  static shortcut = 'selectors.base'
+  static argsSchema: z.ZodType  // schema for select() input
+  static cacheable: boolean = true  // opt-out of caching
+
+  // The core method — override in subclass or graft from module export
+  async select(args, context): Promise<any> {}
+
+  // Dispatch normalizer (like Command.execute)
+  async resolve(args?, source?): Promise<SelectorResult> {}
+}
+```
+
+### Module-Based Pattern (selectors/ folder)
+
+```typescript
+// selectors/package-info.ts
+export const description = 'Returns parsed package.json data'
+export const argsSchema = z.object({ field: z.string().optional() })
+export const cacheable = true
+
+export function cacheKey(args, context) {
+  // return a string key — if unchanged, cached value is returned
+  return context.container.git.sha
+}
+
+export async function select(args, context) {
+  const manifest = context.container.manifest
+  return args.field ? manifest[args.field] : manifest
+}
+```
+
+### Caching Strategy
+
+- Built into the `Selector` base class, powered by `diskCache` feature
+- Subclasses/modules can export a `cacheKey(args, context)` function
+- Default cache key strategy: `hashObject({ selectorName, args, gitSha })`
+- `cacheable: false` opts out entirely
+- Cache is key-invalidated (key changes = miss), no TTL by default
+- The `resolve()` method checks cache before calling `select()`
+
+## Open Questions (Needs Decision)
+
+### 1. Return Shape
+Should `select()` return data directly, or a wrapped result like `{ data, metadata, cached }`?
+
+**Leaning toward:** data directly from `select()`, but `resolve()` (the dispatch method) returns `{ data, cached, cacheKey }` so callers know if it was a cache hit.
+
+### 2. CLI Integration
+Should there be a `luca select <name>` CLI command? Would make selectors usable from the terminal, printing JSON output.
+
+### 3. Cache TTL
+Is pure key-invalidation enough, or do some selectors need time-based expiry?
+
+### 4. Scope of First Delivery
+
+Proposed skateboard:
+- `Selector` base class with `select()` and `resolve()` (cached dispatch)
+- `SelectorsRegistry` with `discover()`
+- Container wiring (`container.selectors`, `container.selector()`)
+- Schemas in `schemas/base.ts`
+- `selectors/` folder discovery via `Helpers` feature
+- Caching integration with `diskCache`
+- Module-based pattern support (export `select` + optional `cacheKey`)
+- `Selector` + `selectors` exported from `@soederpop/luca` barrel + seeded in VM virtual modules
+
+## Codebase Exploration Notes
+
+These are the key files that were studied to inform this design:
+
+- `src/command.ts` — The primary pattern to mirror. `Command` extends `Helper`, has `CommandsRegistry`, `commands` singleton, `Command.register()`, `Command.attach()`, `execute()`/`run()` split, headless capture, `graftModule` support.
+- `src/helper.ts` — Base class providing state, events, options (Zod-validated), introspection, `afterInitialize()` hook.
+- `src/registry.ts` — Abstract `Registry<T>` with `register()`, `lookup()`, `has()`, `available`, `describe()`, `describeAll()`, event bus.
+- `src/graft.ts` — `graftModule()` synthesizes a class from plain module exports. `RESERVED_EXPORTS` list determines what becomes static vs prototype methods.
+- `src/schemas/base.ts` — All Zod schemas. Each helper type has State/Options/Events schemas.
+- `src/node/container.ts` — `NodeContainer` wires everything: side-effect imports, `NodeFeatures` interface, `ClientsAndServersInterface`, `this.use(Command)` pattern.
+- `src/node/features/helpers.ts` — `Helpers` feature: `registryMap`, `RegistryType`, `discoverAll()`, class-based vs config-based discovery, VM module seeding.
+- `src/node/features/disk-cache.ts` — `DiskCache` feature: `get/set/has/rm`, `cacache`-backed, per-project cache dir, `container.utils.hashObject()` for keys.
+- `src/container.ts` — Base `Container`: `createHelperInstance()` with `helperCache` Map, `use()` plugin system, `registerHelperType()`.