@soederpop/luca 0.0.2

package/docs/scaffolds/command.md

@@ -0,0 +1,106 @@
+# Building a Command
+
+A command extends the `luca` CLI. Commands live in a project's `commands/` folder and are automatically discovered. They receive parsed options and a container context.
+
+When to build a command:
+- You need a CLI task for a project (build scripts, generators, automation)
+- You want argument parsing, help text, and container access for free
+- The task should be runnable via `luca yourCommand`
+
+## Imports
+
+```ts
+import { z } from 'zod'
+import { commands, CommandOptionsSchema } from '@soederpop/luca'
+import type { ContainerContext } from '@soederpop/luca'
+```
+
+## Args Schema
+
+Define your command's arguments and flags. Extend `CommandOptionsSchema` which gives you `_` (positional args) and `name` for free.
+
+```ts
+export const argsSchema = CommandOptionsSchema.extend({
+  // Add your flags here. Each becomes a --flag on the CLI.
+  // Example: verbose: z.boolean().default(false).describe('Enable verbose output'),
+  // Example: output: z.string().optional().describe('Output file path'),
+})
+```
+
+## Handler
+
+The handler function receives parsed options and the container context. Use the container for all I/O.
+
+```ts
+export default async function {{camelName}}(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const container = context.container as any
+  const fs = container.feature('fs')
+  const args = container.argv._ as string[]
+
+  // args[0] is your command name, args[1+] are positional arguments
+  // options contains parsed --flags
+
+  // Your implementation here
+}
+```
+
+## Registration
+
+Register the command at the bottom of the file. The `description` shows up in `luca --help`.
+
+```ts
+commands.registerHandler('{{camelName}}', {
+  description: '{{description}}',
+  argsSchema,
+  handler: {{camelName}},
+})
+```
+
+## Module Augmentation
+
+Optional but gives TypeScript autocomplete for `commands.lookup('yourCommand')`.
+
+```ts
+declare module '@soederpop/luca' {
+  interface AvailableCommands {
+    {{camelName}}: ReturnType<typeof commands.registerHandler>
+  }
+}
+```
+
+## Complete Example
+
+```ts
+import { z } from 'zod'
+import { commands, CommandOptionsSchema } from '@soederpop/luca'
+import type { ContainerContext } from '@soederpop/luca'
+
+declare module '@soederpop/luca' {
+  interface AvailableCommands {
+    {{camelName}}: ReturnType<typeof commands.registerHandler>
+  }
+}
+
+export const argsSchema = CommandOptionsSchema.extend({})
+
+export default async function {{camelName}}(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const container = context.container as any
+  const fs = container.feature('fs')
+
+  console.log('{{camelName}} running...')
+}
+
+commands.registerHandler('{{camelName}}', {
+  description: '{{description}}',
+  argsSchema,
+  handler: {{camelName}},
+})
+```
+
+## Conventions
+
+- **File location**: `commands/{{camelName}}.ts` in the project root. The `luca` CLI discovers these automatically.
+- **Naming**: camelCase for both file and registration ID. `luca my-command` maps to `commands/my-command.ts`.
+- **Use the container**: Never import `fs`, `path`, `child_process` directly. Use `container.feature('fs')`, `container.paths`, `container.feature('proc')`.
+- **Positional args**: Access via `container.argv._` — it's an array where `_[0]` is the command name.
+- **Exit codes**: Return nothing for success. Throw for errors — the CLI catches and reports them.

package/docs/scaffolds/endpoint.md

@@ -0,0 +1,176 @@
+# Building an Endpoint
+
+An endpoint is a route handler that `luca serve` auto-discovers and mounts on an Express server. Endpoints live in `endpoints/` and follow a file-based routing convention — each file becomes an API route with automatic validation, OpenAPI spec generation, and rate limiting.
+
+When to build an endpoint:
+- You need a REST API route (GET, POST, PUT, PATCH, DELETE)
+- You want Zod validation, OpenAPI docs, and rate limiting for free
+- You're building an API that `luca serve` manages
+
+## File Location
+
+Endpoints go in `endpoints/` at your project root:
+- `endpoints/health.ts` → `/health`
+- `endpoints/posts.ts` → `/api/posts`
+- `endpoints/posts/[id].ts` → `/api/posts/:id` (requires `path` export)
+
+Run `luca serve` and they're automatically discovered and mounted.
+
+## Imports
+
+```ts
+import { z } from 'zod'
+import type { EndpointContext } from '@soederpop/luca'
+```
+
+That's it. Endpoints are lightweight — just exports and functions.
+
+## Required Exports
+
+Every endpoint MUST export a `path` string:
+
+```ts
+export const path = '/api/{{camelName}}'
+export const description = '{{description}}'
+export const tags = ['{{camelName}}']
+```
+
+## Handler Functions
+
+Export named functions for each HTTP method you support. Each receives validated parameters and an `EndpointContext`:
+
+```ts
+export async function get(params: any, ctx: EndpointContext) {
+  const fs = ctx.container.feature('fs')
+  // Your logic here
+  return { message: 'ok' }
+}
+
+export async function post(params: z.infer<typeof postSchema>, ctx: EndpointContext) {
+  // Create something
+  return { created: true }
+}
+```
+
+The `EndpointContext` gives you:
+- `ctx.container` — the luca container (access any feature, client, etc.)
+- `ctx.request` — Express request object
+- `ctx.response` — Express response object
+- `ctx.query` — parsed query string
+- `ctx.body` — parsed request body
+- `ctx.params` — URL parameters (`:id`, etc.)
+
+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`:
+
+```ts
+export const getSchema = z.object({
+  q: z.string().optional().describe('Search query'),
+  limit: z.number().default(20).describe('Max results'),
+})
+
+export const postSchema = z.object({
+  title: z.string().min(1).describe('Item title'),
+  body: z.string().min(1).describe('Item content'),
+})
+```
+
+Invalid requests automatically return 400 with Zod error details. Schemas also feed the auto-generated OpenAPI spec.
+
+## Rate Limiting
+
+Export rate limit config to protect endpoints:
+
+```ts
+// Global rate limit for all methods
+export const rateLimit = { maxRequests: 100, windowSeconds: 60 }
+
+// Per-method rate limit
+export const postRateLimit = { maxRequests: 10, windowSeconds: 1 }
+```
+
+## Delete Handler
+
+`delete` is a reserved word in JS. Use an alias:
+
+```ts
+const del = async (params: any, ctx: EndpointContext) => {
+  return { deleted: true }
+}
+export { del as delete }
+```
+
+## Complete Example
+
+A CRUD endpoint for a resource:
+
+```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) {
+  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) {
+  return { item: { id: '1', ...params }, message: 'Created' }
+}
+```
+
+## Dynamic Route Example
+
+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) {
+  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) {
+  const { id } = ctx.params
+  return { item: { id, ...params }, message: 'Updated' }
+}
+
+const del = async (params: any, ctx: EndpointContext) => {
+  const { id } = ctx.params
+  return { message: `Deleted ${id}` }
+}
+export { del as delete }
+```
+
+## Conventions
+
+- **File = route**: The file path maps to the URL path. `endpoints/users.ts` serves `/api/users`.
+- **Export `path`**: Every endpoint must export a `path` string. This is the mounted route.
+- **Use Zod schemas**: Name them `getSchema`, `postSchema`, etc. They validate AND document.
+- **Use the container**: Access features via `ctx.container.feature('fs')`, not Node.js imports.
+- **Return objects**: Handler return values are JSON-serialized. Use `ctx.response` only for streaming or custom status codes.
+- **OpenAPI for free**: Your `path`, `description`, `tags`, and schemas automatically generate an OpenAPI spec at `/openapi.json`.

package/docs/scaffolds/feature.md

@@ -0,0 +1,148 @@
+# Building a Feature
+
+A feature is a container-managed capability — something your application needs that lives on the machine (file I/O, caching, encryption, etc). Features are lazy-loaded, observable, and self-documenting.
+
+When to build a feature:
+- You need a reusable local capability (not a network call — that's a client)
+- You want state management, events, and introspection for free
+- You're wrapping a library so the rest of the codebase uses a uniform interface
+
+## Imports
+
+```ts
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '@soederpop/luca'
+import { Feature, features } from '@soederpop/luca'
+import type { ContainerContext } 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.
+
+## Schemas
+
+Define the shape of your feature's state, options, and events using Zod. Every field must have a `.describe()` — this becomes the documentation.
+
+```ts
+export const {{PascalName}}StateSchema = FeatureStateSchema.extend({
+  // Add your state fields here. These are observable — changes emit events.
+  // Example: itemCount: z.number().default(0).describe('Number of items stored'),
+})
+export type {{PascalName}}State = z.infer<typeof {{PascalName}}StateSchema>
+
+export const {{PascalName}}OptionsSchema = FeatureOptionsSchema.extend({
+  // Add constructor options here. Validated when the feature is created.
+  // Example: directory: z.string().optional().describe('Storage directory path'),
+})
+export type {{PascalName}}Options = z.infer<typeof {{PascalName}}OptionsSchema>
+
+export const {{PascalName}}EventsSchema = FeatureEventsSchema.extend({
+  // Each key is an event name. Value is z.tuple() of listener arguments.
+  // Example: itemAdded: z.tuple([z.string().describe('Item key')]).describe('Emitted when an item is added'),
+})
+```
+
+## Class
+
+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`.
+
+```ts
+/**
+ * {{description}}
+ *
+ * @example
+ * ```typescript
+ * const {{camelName}} = container.feature('{{camelName}}')
+ * ```
+ *
+ * @extends Feature
+ */
+export class {{PascalName}} extends Feature<{{PascalName}}State, {{PascalName}}Options> {
+  static override shortcut = 'features.{{camelName}}' as const
+  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
+  }
+
+  // Add your methods here. Every public method needs JSDoc.
+}
+```
+
+## Module Augmentation
+
+This is what gives `container.feature('yourName')` TypeScript autocomplete. Without it, the feature works but TypeScript won't know about it.
+
+```ts
+declare module '@soederpop/luca' {
+  interface AvailableFeatures {
+    {{camelName}}: typeof {{PascalName}}
+  }
+}
+```
+
+## Registration
+
+The last line of the file registers the feature in the global registry. This must happen at module level (not inside a function).
+
+```ts
+export default features.register('{{camelName}}', {{PascalName}})
+```
+
+## Complete Example
+
+Here's a minimal but complete feature. This is what a real feature file looks like:
+
+```ts
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema } from '@soederpop/luca'
+import { Feature, features } from '@soederpop/luca'
+import type { ContainerContext } from '@soederpop/luca'
+
+declare module '@soederpop/luca' {
+  interface AvailableFeatures {
+    {{camelName}}: typeof {{PascalName}}
+  }
+}
+
+export const {{PascalName}}StateSchema = FeatureStateSchema.extend({})
+export type {{PascalName}}State = z.infer<typeof {{PascalName}}StateSchema>
+
+export const {{PascalName}}OptionsSchema = FeatureOptionsSchema.extend({})
+export type {{PascalName}}Options = z.infer<typeof {{PascalName}}OptionsSchema>
+
+/**
+ * {{description}}
+ *
+ * @example
+ * ```typescript
+ * const {{camelName}} = container.feature('{{camelName}}')
+ * ```
+ *
+ * @extends Feature
+ */
+export class {{PascalName}} extends Feature<{{PascalName}}State, {{PascalName}}Options> {
+  static override shortcut = 'features.{{camelName}}' as const
+  static override stateSchema = {{PascalName}}StateSchema
+  static override optionsSchema = {{PascalName}}OptionsSchema
+  static override description = '{{description}}'
+
+  constructor(options: {{PascalName}}Options, context: ContainerContext) {
+    super(options, context)
+  }
+}
+
+export default features.register('{{camelName}}', {{PascalName}})
+```
+
+## Conventions
+
+- **Naming**: PascalCase for class, camelCase for registration ID. The file name should be kebab-case (e.g. `disk-cache.ts`).
+- **JSDoc**: Every public method, getter, and the class itself needs a JSDoc block. Include `@example` with working code.
+- **Describe everything**: Every Zod field needs `.describe()`. Every event tuple argument needs `.describe()`. This IS the documentation.
+- **No Node builtins in consumer code**: If your feature wraps `fs` or `crypto`, that's fine inside the feature. But code that USES your feature should never import those directly.
+- **State is observable**: Use `this.state.set()` and `this.state.get()`. Don't use plain instance properties for data that should be reactive.
+- **Events for lifecycle**: Emit events for significant state changes so consumers can react.

package/docs/scaffolds/server.md

@@ -0,0 +1,187 @@
+# Building a Server
+
+A server is a container-managed listener — something that accepts connections and handles requests. Servers manage their own lifecycle (configure, start, stop) and expose observable state.
+
+When to build a server:
+- You need to accept incoming connections (HTTP, WebSocket, custom protocol)
+- You want lifecycle management, port handling, and observability for free
+- You're wrapping a server library so the codebase uses `container.server('name')`
+
+## Imports
+
+```ts
+import { z } from 'zod'
+import { Server, servers } from '@soederpop/luca'
+import { ServerStateSchema, ServerOptionsSchema, ServerEventsSchema } from '@soederpop/luca'
+import type { ContainerContext, NodeContainer } from '@soederpop/luca'
+import type { ServersInterface } from '@soederpop/luca'
+```
+
+## Schemas
+
+```ts
+export const {{PascalName}}StateSchema = ServerStateSchema.extend({
+  // Add your state fields here.
+  // Example: connectionCount: z.number().default(0).describe('Active connections'),
+})
+export type {{PascalName}}State = z.infer<typeof {{PascalName}}StateSchema>
+
+export const {{PascalName}}OptionsSchema = ServerOptionsSchema.extend({
+  // Add constructor options here. port and host come from ServerOptionsSchema.
+  // Example: cors: z.boolean().default(true).describe('Enable CORS'),
+})
+export type {{PascalName}}Options = z.infer<typeof {{PascalName}}OptionsSchema>
+
+export const {{PascalName}}EventsSchema = ServerEventsSchema.extend({
+  // Add your events here.
+  // Example: connection: z.tuple([z.string().describe('Client ID')]).describe('New client connected'),
+})
+```
+
+## Class
+
+```ts
+/**
+ * {{description}}
+ *
+ * @example
+ * ```typescript
+ * const {{camelName}} = container.server('{{camelName}}', { port: 3000 })
+ * await {{camelName}}.start()
+ * ```
+ *
+ * @extends Server
+ */
+export class {{PascalName}} extends Server<{{PascalName}}State, {{PascalName}}Options> {
+  static override shortcut = 'servers.{{camelName}}' as const
+  static override stateSchema = {{PascalName}}StateSchema
+  static override optionsSchema = {{PascalName}}OptionsSchema
+  static override eventsSchema = {{PascalName}}EventsSchema
+  static override description = '{{description}}'
+
+  static override attach(container: NodeContainer & ServersInterface) {
+    return container
+  }
+
+  override async configure() {
+    if (this.isConfigured) return this
+    // Set up the underlying server here
+    this.state.set('configured', true)
+    return this
+  }
+
+  override async start(options?: { port?: number }) {
+    if (this.isListening) return this
+    if (!this.isConfigured) await this.configure()
+
+    const port = options?.port || this.options.port || 3000
+    // Start listening here
+    this.state.set('port', port)
+    this.state.set('listening', true)
+    return this
+  }
+
+  override async stop() {
+    if (this.isStopped) return this
+    // Clean up connections here
+    this.state.set('listening', false)
+    this.state.set('stopped', true)
+    return this
+  }
+}
+```
+
+## Module Augmentation
+
+```ts
+declare module '@soederpop/luca' {
+  interface AvailableServers {
+    {{camelName}}: typeof {{PascalName}}
+  }
+}
+```
+
+## Registration
+
+```ts
+export default servers.register('{{camelName}}', {{PascalName}})
+```
+
+## Complete Example
+
+```ts
+import { z } from 'zod'
+import { Server, servers } from '@soederpop/luca'
+import { ServerStateSchema, ServerOptionsSchema, ServerEventsSchema } from '@soederpop/luca'
+import type { ContainerContext, NodeContainer } from '@soederpop/luca'
+import type { ServersInterface } from '@soederpop/luca'
+
+declare module '@soederpop/luca' {
+  interface AvailableServers {
+    {{camelName}}: typeof {{PascalName}}
+  }
+}
+
+export const {{PascalName}}StateSchema = ServerStateSchema.extend({})
+export type {{PascalName}}State = z.infer<typeof {{PascalName}}StateSchema>
+
+export const {{PascalName}}OptionsSchema = ServerOptionsSchema.extend({})
+export type {{PascalName}}Options = z.infer<typeof {{PascalName}}OptionsSchema>
+
+export const {{PascalName}}EventsSchema = ServerEventsSchema.extend({})
+
+/**
+ * {{description}}
+ *
+ * @example
+ * ```typescript
+ * const {{camelName}} = container.server('{{camelName}}', { port: 3000 })
+ * await {{camelName}}.start()
+ * ```
+ *
+ * @extends Server
+ */
+export class {{PascalName}} extends Server<{{PascalName}}State, {{PascalName}}Options> {
+  static override shortcut = 'servers.{{camelName}}' as const
+  static override stateSchema = {{PascalName}}StateSchema
+  static override optionsSchema = {{PascalName}}OptionsSchema
+  static override eventsSchema = {{PascalName}}EventsSchema
+  static override description = '{{description}}'
+
+  static override attach(container: NodeContainer & ServersInterface) {
+    return container
+  }
+
+  override async configure() {
+    if (this.isConfigured) return this
+    this.state.set('configured', true)
+    return this
+  }
+
+  override async start(options?: { port?: number }) {
+    if (this.isListening) return this
+    if (!this.isConfigured) await this.configure()
+    const port = options?.port || this.options.port || 3000
+    this.state.set('port', port)
+    this.state.set('listening', true)
+    return this
+  }
+
+  override async stop() {
+    if (this.isStopped) return this
+    this.state.set('listening', false)
+    this.state.set('stopped', true)
+    return this
+  }
+}
+
+export default servers.register('{{camelName}}', {{PascalName}})
+```
+
+## Conventions
+
+- **Lifecycle**: Implement `configure()`, `start()`, and `stop()`. Check guards (`isConfigured`, `isListening`, `isStopped`) at the top of each.
+- **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`.

package/docs/tasks/web-container-helper-discovery.md

@@ -0,0 +1,71 @@
+---
+repeatable: false
+---
+
+# Implement Helper Discovery for WebContainer
+
+The NodeContainer has a `helpers` feature (`src/node/features/helpers.ts`) that provides unified discovery across all registries. The WebContainer has no equivalent. Implement helper discovery for the web container.
+
+## Context
+
+The node `Helpers` feature provides:
+- `container.helpers.discover('features')` — scan conventional folders and register what it finds
+- `container.helpers.discoverAll()` — discover across all registry types
+- `container.helpers.available` — unified view of all registries
+- `container.helpers.lookup(type, name)` and `container.helpers.describe(type, name)`
+
+The web container has `features` and `clients` registries (Client is attached via `extension.ts`, which calls `container.use(Client)` and triggers `registerHelperType('clients', 'client')`). It has `RestClient` and `SocketClient` available. No servers, commands, or endpoints registries.
+
+## What to Build
+
+### 1. Create `src/web/features/helpers.ts`
+
+Port the node `Helpers` feature to work in the browser environment. Key differences from the node version:
+
+- **No filesystem scanning** — the browser can't scan directories. Instead, discovery should work via explicit registration or a manifest/config object that lists available helpers and their import paths.
+- **Registry scope** — cover `features` and `clients` (both already attached). The `registryMap` should reflect what the web container actually has.
+- **No dynamic `import()` from disk** — helper modules need to be bundled or loaded via URL. Consider accepting a map of `{ name: () => import('./my-feature.js') }` lazy loaders.
+- **Keep the same public API surface** — `discover()`, `discoverAll()`, `available`, `lookup()`, `describe()` should all work identically from the consumer's perspective.
+
+### 2. Register it in `src/web/extension.ts`
+
+Add the helpers feature to the web extension so it's available as `container.feature('helpers')` / `container.helpers`.
+
+### 3. Approach for Browser Discovery
+
+Since there's no filesystem to scan, discovery needs a different mechanism. Recommended approach:
+
+```typescript
+// Option A: Manifest-based discovery
+const helpers = container.feature('helpers', {
+  enable: true,
+  manifest: {
+    features: {
+      myFeature: () => import('./features/my-feature.js'),
+    }
+  }
+})
+await helpers.discoverAll()
+```
+
+This keeps the same `discover()` / `discoverAll()` API but replaces folder scanning with a lazy-import manifest. The manifest can be generated at build time by a bundler plugin or written by hand.
+
+### 4. Shared Base
+
+Look at whether a base `Helpers` class can be extracted to `src/features/helpers.ts` (universal, not node or web specific) with the shared API surface (`available`, `lookup`, `describe`, state/events schemas). Then `src/node/features/helpers.ts` and `src/web/features/helpers.ts` extend it with their environment-specific discovery strategies (filesystem vs manifest).
+
+## Files to Touch
+
+- `src/features/helpers.ts` — new, shared base class with common API
+- `src/web/features/helpers.ts` — new, web-specific discovery via manifest
+- `src/node/features/helpers.ts` — refactor to extend shared base
+- `src/web/extension.ts` — register the web helpers feature
+- `src/schemas/base.ts` — only if new shared schemas are needed
+
+## Acceptance Criteria
+
+- `container.helpers.available` works in both node and web containers
+- `container.helpers.discover('features')` works in web via manifest config
+- `container.helpers.lookup()` and `container.helpers.describe()` work in web
+- Node behavior is unchanged (existing tests still pass)
+- The shared base class eliminates duplicated logic between node and web

package/docs/todos.md

@@ -0,0 +1 @@
+- make container.start() meaningful. i like the idea of container.use() accepting in addition to the current shape, an async function and container.start() basically running all of those functions.