@wooksjs/event-core 0.6.5 → 0.7.0

package/package.json

@@ -1,17 +1,12 @@
 {
   "name": "@wooksjs/event-core",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "description": "@wooksjs/event-core",
   "keywords": [
-    "api",
-    "app",
     "composables",
+    "context",
+    "event",
     "framework",
-    "http",
-    "prostojs",
-    "rest",
-    "restful",
-    "web",
     "wooks"
   ],
   "homepage": "https://github.com/wooksjs/wooksjs/tree/main/packages/event-core#readme",
@@ -25,8 +20,13 @@
     "url": "git+https://github.com/wooksjs/wooksjs.git",
     "directory": "packages/event-core"
   },
+  "bin": {
+    "wooksjs-event-core-skill": "./scripts/setup-skills.js"
+  },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "scripts/setup-skills.js"
   ],
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -39,14 +39,12 @@
       "import": "./dist/index.mjs"
     }
   },
-  "dependencies": {
-    "@prostojs/logger": "^0.4.3"
-  },
   "devDependencies": {
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   },
   "scripts": {
-    "build": "rolldown -c ../../rolldown.config.mjs"
+    "build": "rolldown -c ../../rolldown.config.mjs",
+    "setup-skills": "node ./scripts/setup-skills.js"
   }
 }

package/scripts/setup-skills.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/* prettier-ignore */
+import fs from 'fs'
+import path from 'path'
+import os from 'os'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const SKILL_NAME = 'wooksjs-event-core'
+const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
+
+if (!fs.existsSync(SKILL_SRC)) {
+  console.error(`No skills found at ${SKILL_SRC}`)
+  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
+  process.exit(1)
+}
+
+const AGENTS = {
+  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
+  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
+  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
+  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
+  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
+}
+
+const args = process.argv.slice(2)
+const isGlobal = args.includes('--global') || args.includes('-g')
+const isPostinstall = args.includes('--postinstall')
+let installed = 0, skipped = 0
+const installedDirs = []
+
+for (const [agentName, cfg] of Object.entries(AGENTS)) {
+  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
+  const agentRootDir = path.dirname(cfg.global) // Check if the agent has ever been installed globally
+
+  // In postinstall mode: silently skip agents that aren't set up globally
+  if (isPostinstall || isGlobal) {
+    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
+  }
+
+  const dest = path.join(targetBase, SKILL_NAME)
+  try {
+    fs.mkdirSync(dest, { recursive: true })
+    fs.cpSync(SKILL_SRC, dest, { recursive: true })
+    console.log(`✅  ${agentName}: installed to ${dest}`)
+    installed++
+    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
+  } catch (err) {
+    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
+  }
+}
+
+// Add locally-installed skill dirs to .gitignore
+if (!isGlobal && installedDirs.length > 0) {
+  const gitignorePath = path.join(process.cwd(), '.gitignore')
+  let gitignoreContent = ''
+  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
+  const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
+  if (linesToAdd.length > 0) {
+    const hasHeader = gitignoreContent.includes('# AI agent skills')
+    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
+      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
+      + linesToAdd.join('\n') + '\n'
+    fs.appendFileSync(gitignorePath, block)
+    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
+  }
+}
+
+if (installed === 0 && isPostinstall) {
+  // Silence is fine — no agents present, nothing to do
+} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
+  console.log('No agent directories detected. Try --global or run without it for project-local install.')
+} else if (installed === 0) {
+  console.log('Nothing installed. Run without --global to install project-locally.')
+} else {
+  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
+}

package/skills/wooksjs-event-core/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: wooksjs-event-core
+description: Use this skill when working with @wooksjs/event-core — to create typed context slots with key(), build lazy cached computations with cached() and cachedBy(), define composables with defineWook(), define event kind schemas with defineEventKind() and slot(), manage EventContext lifecycle with run()/current()/createEventContext(), or build custom Wooks adapters. Covers useLogger(), useRouteParams(), useEventId(), and AsyncLocalStorage-based context propagation.
+---
+
+# @wooksjs/event-core
+
+Typed, per-event context with lazy cached computations, composable API (`defineWook`), and `AsyncLocalStorage` propagation. The foundation layer for all `@wooksjs` adapters (HTTP, CLI, workflows).
+
+## How to use this skill
+
+Read the domain file that matches the task. Do not load all files — only what you need.
+
+| Domain                | File                             | Load when...                                                                                                              |
+| --------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Core concepts & setup | [core.md](core.md)               | Starting a new project, understanding the mental model, seeing all exports                                                |
+| Primitives            | [primitives.md](primitives.md)   | Creating typed slots (`key`), lazy computations (`cached`, `cachedBy`), or event kind schemas (`slot`, `defineEventKind`) |
+| Composables           | [composables.md](composables.md) | Building custom composables with `defineWook`, using built-in composables (`useRouteParams`, `useEventId`, `useLogger`)   |
+| Context & runtime     | [context.md](context.md)         | Managing `EventContext` lifecycle, `run`/`current`/`createEventContext`, async propagation, performance optimization      |
+
+## Quick reference
+
+```ts
+import {
+  // primitives
+  key,
+  cached,
+  cachedBy,
+  slot,
+  defineEventKind,
+  defineWook,
+  // context
+  EventContext,
+  run,
+  current,
+  tryGetCurrent,
+  createEventContext,
+  // composables
+  useRouteParams,
+  useEventId,
+  useLogger,
+  // standard keys
+  routeParamsKey,
+  eventTypeKey,
+  // observability
+  ContextInjector,
+  getContextInjector,
+  replaceContextInjector,
+} from '@wooksjs/event-core'
+```

package/skills/wooksjs-event-core/composables.md

@@ -0,0 +1,200 @@
+# Composables — @wooksjs/event-core
+
+> `defineWook` and the built-in composables: `useRouteParams`, `useEventId`, `useLogger`.
+
+## Concepts
+
+A **composable** is a function that accesses per-event contextual data. Call it — get typed data back. No arguments needed (context resolved via `AsyncLocalStorage`).
+
+`defineWook(factory)` is the primitive that creates composables. The factory runs once per `EventContext`, and the result is cached. Every subsequent call within the same event returns the same object.
+
+All built-in composables across the Wooks ecosystem (`useRequest`, `useResponse`, `useBody`, `useCookies`, etc.) are built with `defineWook`.
+
+## API Reference
+
+### `defineWook<T>(factory: (ctx: EventContext) => T): (ctx?: EventContext) => T`
+
+Creates a composable with per-event caching. Internally wraps the factory in a `cached()` slot.
+
+```ts
+import { defineWook, defineEventKind, slot } from '@wooksjs/event-core'
+
+const http = defineEventKind('http', {
+  method: slot<string>(),
+  path: slot<string>(),
+})
+
+const useRequest = defineWook((ctx) => ({
+  method: ctx.get(http.keys.method),
+  path: ctx.get(http.keys.path),
+}))
+
+// In a handler:
+const { method, path } = useRequest()
+```
+
+**Caching guarantee:** The factory runs exactly once per event context. Subsequent calls return the same object:
+
+```ts
+const a = useRequest()
+const b = useRequest()
+a === b // true — same object reference
+```
+
+**Optional explicit context:** Pass `ctx` to skip the `AsyncLocalStorage` lookup:
+
+```ts
+const ctx = current()
+const { method } = useRequest(ctx)
+const { parseBody } = useBody(ctx)
+```
+
+### `useRouteParams<T>(ctx?): { params: T; get: (name) => T[K] }`
+
+Returns route parameters set by the router. Generic `T` defaults to `Record<string, string | string[]>`.
+
+```ts
+import { useRouteParams } from '@wooksjs/event-core'
+
+// Given route /users/:id
+const { params, get } = useRouteParams<{ id: string }>()
+params.id // 'abc'
+get('id') // 'abc'
+```
+
+### `useEventId(ctx?): { getId: () => string }`
+
+Returns a lazy UUID for the current event. The UUID is generated on first call to `getId()` and cached.
+
+```ts
+import { useEventId } from '@wooksjs/event-core'
+
+const { getId } = useEventId()
+getId() // 'a1b2c3d4-...' (stable for this event)
+```
+
+### `useLogger(ctx?): Logger`
+
+Returns the logger from the current event context. Shorthand for `(ctx ?? current()).logger`.
+
+```ts
+import { useLogger } from '@wooksjs/event-core'
+
+const log = useLogger()
+log.info('handling request')
+```
+
+## Common Patterns
+
+### Pattern: Composable with lazy properties
+
+Wrap non-trivial computations in thunks so they only run when accessed:
+
+```ts
+const useRequest = defineWook((ctx) => ({
+  method: ctx.get(http.keys.method), // cheap — direct key lookup
+  query: () => ctx.get(parsedQuery), // deferred until called
+  cookies: () => ctx.get(parsedCookies), // deferred until called
+}))
+
+// Only method is computed eagerly:
+const { method } = useRequest()
+// query is only computed if accessed:
+const q = useRequest().query()
+```
+
+### Pattern: Composable with async cached values
+
+Combine `defineWook` with `cached` for async computations:
+
+```ts
+const parsedBody = cached(async (ctx) => {
+  const buf = await ctx.get(rawBody)
+  return JSON.parse(buf.toString())
+})
+
+const useBody = defineWook((ctx) => ({
+  parseBody: () => ctx.get(parsedBody),
+}))
+
+// In handler:
+const { parseBody } = useBody()
+const body = await parseBody() // parses once
+const again = await parseBody() // cache hit, same object
+```
+
+### Pattern: Class-based composable for method-heavy APIs
+
+When a composable exposes many methods, use a class to avoid per-event closure allocation:
+
+```ts
+class ResponseState {
+  status = 200
+  body: unknown = undefined
+  readonly headers = new Map<string, string>()
+
+  setHeader(name: string, value: string) {
+    this.headers.set(name, value)
+    return this
+  }
+  setStatus(code: number) {
+    this.status = code
+    return this
+  }
+  json(data: unknown) {
+    this.body = data
+    return this
+  }
+}
+
+const useResponse = defineWook(() => new ResponseState())
+```
+
+Methods live on the prototype — zero closures per event.
+
+### Pattern: Composable depending on another composable
+
+Composables can call other composables inside their factory:
+
+```ts
+const useCurrentUser = defineWook((ctx) => {
+  const { basicCredentials } = useAuthorization(ctx)
+  const username = basicCredentials()?.username
+  return {
+    username,
+    profile: async () => (username ? await db.findUser(username) : null),
+  }
+})
+```
+
+Pass `ctx` to avoid redundant `AsyncLocalStorage` lookups.
+
+### Pattern: Plain function for single-value access
+
+`defineWook` adds caching overhead. For trivial single-value access, use a plain function:
+
+```ts
+// Overkill — caching overhead > value cost
+const useMethod = defineWook((ctx) => ctx.get(http.keys.method))
+
+// Better — one Map.get, no caching layer
+function useMethod(ctx?: EventContext): string {
+  return (ctx ?? current()).get(http.keys.method) ?? 'GET'
+}
+```
+
+## Best Practices
+
+- Use `defineWook` when the factory returns an object with multiple properties or methods
+- Use plain functions for trivial single-value access
+- Always accept optional `ctx` parameter in composables for performance
+- Pass `ctx` explicitly when calling multiple composables in sequence
+- Use thunks for non-trivial properties in the returned object
+- Use classes for composables with 4+ methods
+
+## Gotchas
+
+- `defineWook` factory receives `ctx` as parameter — use it instead of calling `current()` inside
+- The factory runs once per context — don't put per-call logic in it (use thunks for that)
+- Calling a composable outside an event context throws `No active event context`
+- Different event contexts get different composable instances — the cache is per-context

package/skills/wooksjs-event-core/context.md

@@ -0,0 +1,270 @@
+# Context & runtime — @wooksjs/event-core
+
+> `EventContext` class, `run`/`current`/`createEventContext`, async propagation, and performance.
+
+## Concepts
+
+Every event in Wooks gets its own `EventContext` — a lightweight container backed by `Map<number, unknown>`. The context is propagated through the async call stack via Node.js `AsyncLocalStorage`.
+
+The lifecycle:
+
+1. Create an `EventContext` (or use `createEventContext`), optionally linking a `parent` context
+2. Seed it with event-specific data via `ctx.seed(kind, seeds)`
+3. Enter the `AsyncLocalStorage` scope with `run(ctx, fn)`
+4. Inside `fn`, composables resolve the context via `current()`
+
+Adapters (HTTP, CLI, etc.) handle steps 1-3. Your handler code only interacts with composables.
+
+## API Reference
+
+### `EventContext`
+
+```ts
+import { EventContext } from '@wooksjs/event-core'
+
+const ctx = new EventContext({ logger })
+```
+
+**Constructor options:**
+
+```ts
+interface EventContextOptions {
+  logger: Logger
+  parent?: EventContext
+}
+```
+
+Every context requires a `Logger`. Access it via `ctx.logger`.
+
+When `parent` is provided, the child context forms a **parent chain**. Lookups via `get()`, `set()`, and `has()` traverse the chain (local first, then parent, then grandparent, etc.). This replaces the old pattern of attaching multiple kinds to a single context — instead, create child contexts with parent links:
+
+```ts
+const parentCtx = new EventContext({ logger })
+parentCtx.seed(httpKind, { method: 'GET', path: '/api' })
+
+const childCtx = new EventContext({ logger, parent: parentCtx })
+childCtx.seed(workflowKind, { triggerId: 'deploy-42' })
+
+// child can see its own data AND parent data
+childCtx.get(httpKind.keys.method) // 'GET' (found in parent)
+childCtx.get(workflowKind.keys.triggerId) // 'deploy-42' (found locally)
+```
+
+**Methods:**
+
+#### `ctx.get<T>(accessor: Key<T> | Cached<T>): T`
+
+Get a value by key or cached accessor. **Traverses the parent chain:** checks local context first, then parent, grandparent, and so on.
+
+- For `Key<T>`: returns the first value found in the chain. Throws `Key "name" is not set` if not found in any context.
+- For `Cached<T>`: if a computed value is found anywhere in the parent chain, returns it (no re-computation). If not found in any context, computes and caches the result **locally**.
+
+#### `ctx.set<T>(key: Key<T> | Cached<T>, value: T): void`
+
+Set a value for a key. **Traverses the parent chain:** if the key already exists somewhere in the chain, writes to that context. If the key is new (not found in any ancestor), writes locally. Works with `undefined`, `null`, and falsy values.
+
+#### `ctx.has(accessor: Accessor<any>): boolean`
+
+Check if a slot has been set or computed. **Traverses the parent chain.** Returns `true` if the slot is found in any context in the chain. Returns `false` for unset keys and uncomputed cached values across the entire chain.
+
+#### `ctx.getOwn<T>(accessor: Key<T> | Cached<T>): T`
+
+Like `get()`, but **local only** — does not traverse the parent chain. Returns the value from this context only. Throws if not set locally.
+
+#### `ctx.setOwn<T>(key: Key<T> | Cached<T>, value: T): void`
+
+Like `set()`, but **local only** — always writes to this context, even if the key exists in a parent.
+
+#### `ctx.hasOwn(accessor: Accessor<any>): boolean`
+
+Like `has()`, but **local only** — returns `true` only if the slot is set in this context, ignoring parents.
+
+#### `ctx.seed(kind, seeds[, fn])`
+
+Populate context from an `EventKind` schema (previously called `attach`):
+
+```ts
+const http = defineEventKind('http', {
+  method: slot<string>(),
+  path: slot<string>(),
+})
+
+ctx.seed(http, { method: 'GET', path: '/api' })
+ctx.get(http.keys.method) // 'GET'
+```
+
+Also sets `eventTypeKey` to the kind's name.
+
+Overloaded: can accept an optional callback that runs immediately after seeding:
+
+```ts
+ctx.seed(http, seeds, () => {
+  // seeds are available here
+})
+```
+
+### `run<R>(ctx: EventContext, fn: () => R): R`
+
+Execute `fn` within the `AsyncLocalStorage` scope of `ctx`. Returns the fn's return value. Works with async functions.
+
+```ts
+const ctx = new EventContext({ logger })
+const result = run(ctx, () => {
+  // current() returns ctx here
+  return 'hello'
+})
+// result === 'hello'
+```
+
+Supports nesting — inner `run` creates a child scope:
+
+```ts
+run(outer, () => {
+  current() === outer // true
+  run(inner, () => {
+    current() === inner // true
+  })
+  current() === outer // true (restored)
+})
+```
+
+### `current(): EventContext`
+
+Get the active `EventContext` from the `AsyncLocalStorage` scope. Throws `[Wooks] No active event context` if called outside a `run` scope.
+
+### `tryGetCurrent(): EventContext | undefined`
+
+Like `current()` but returns `undefined` instead of throwing.
+
+### `createEventContext(options, fn): R`
+
+### `createEventContext(options, kind, seeds, fn): R`
+
+Convenience: creates a context, optionally seeds a kind, and runs `fn` inside `AsyncLocalStorage`:
+
+```ts
+// Bare context
+createEventContext({ logger }, () => {
+  const ctx = current()
+  // ...
+})
+
+// With kind + seeds
+createEventContext({ logger }, httpKind, { method: 'GET', path: '/' }, () => {
+  current().get(httpKind.keys.method) // 'GET'
+})
+```
+
+Returns the fn's return value. Works with async callbacks.
+
+### `useLogger(ctx?: EventContext): Logger`
+
+Shorthand for `(ctx ?? current()).logger`.
+
+## Version safety
+
+`@wooksjs/event-core` uses a global `Symbol.for('wooks.core.asyncStorage')` to ensure a single `AsyncLocalStorage` instance across the process. If two incompatible versions are loaded, it throws at import time:
+
+```
+[wooks] Incompatible versions of @wooksjs/event-core detected: existing v0.6.6, loading v0.7.0
+```
+
+This prevents subtle bugs from multiple context stores.
+
+## Common Patterns
+
+### Pattern: Custom adapter
+
+Build an adapter that creates contexts and runs handlers:
+
+```ts
+import { EventContext, defineEventKind, slot, run } from '@wooksjs/event-core'
+
+const myKind = defineEventKind('my-event', {
+  data: slot<unknown>(),
+})
+
+function handleEvent(data: unknown, handler: () => unknown, parent?: EventContext) {
+  const ctx = new EventContext({ logger: console, parent })
+  ctx.seed(myKind, { data })
+  return run(ctx, handler)
+}
+```
+
+### Pattern: Child contexts with parent links
+
+Instead of attaching multiple kinds to a single context, create child contexts with parent links. Each child sees its own data plus everything in the parent chain:
+
+```ts
+createEventContext({ logger }, httpKind, httpSeeds, () => {
+  const parentCtx = current()
+
+  // Create a child context for workflow-specific data
+  const childCtx = new EventContext({ logger, parent: parentCtx })
+  childCtx.seed(workflowKind, { triggerId: 'deploy-42', payload })
+
+  run(childCtx, () => {
+    // Both HTTP and workflow composables work
+    const { method } = useRequest() // found via parent chain
+    const { triggerId } = useWorkflow() // found locally
+  })
+})
+```
+
+The parent chain allows layered contexts — for example, a base HTTP context can be shared across sub-handlers, each with their own child context carrying handler-specific state.
+
+### Pattern: Resolve context once for hot paths
+
+Each composable call without `ctx` hits `AsyncLocalStorage.getStore()`. For hot paths:
+
+```ts
+// 4 ALS lookups
+const { method } = useRequest()
+const { parseBody } = useBody()
+const session = getCookie('session')
+const log = useLogger()
+
+// 1 ALS lookup
+const ctx = current()
+const { method } = useRequest(ctx)
+const { parseBody } = useBody(ctx)
+const session = getCookie('session', ctx)
+const log = ctx.logger
+```
+
+## ContextInjector (observability)
+
+`ContextInjector` is a hook point for observability tools (OpenTelemetry, etc.). The default implementation is a no-op pass-through.
+
+```ts
+import { ContextInjector, replaceContextInjector } from '@wooksjs/event-core'
+
+class OtelInjector extends ContextInjector<string> {
+  with<T>(name: string, attributes: Record<string, any>, cb: () => T): T {
+    return tracer.startActiveSpan(name, { attributes }, () => cb())
+  }
+}
+
+replaceContextInjector(new OtelInjector())
+```
+
+The injector's `with()` method wraps `createEventContext` callbacks and handler invocations.
+
+## Best Practices
+
+- Let adapters handle context creation — in handler code, just use composables
+- Pass `ctx` explicitly in hot paths with multiple composable calls
+- Use `tryGetCurrent()` in library code that may run outside event scope
+- Keep `Logger` simple — the interface is `info/warn/error/debug` with optional `topic()`
+- Prefer parent-linked child contexts over seeding multiple kinds into one context — the parent chain keeps each layer's data isolated while still accessible
+- Use `getOwn()`/`setOwn()`/`hasOwn()` when you need to guarantee local-only access and avoid unintended reads from or writes to parent contexts
+
+## Gotchas
+
+- `current()` throws outside `run()` scope — use `tryGetCurrent()` if that's expected
+- `AsyncLocalStorage` propagates through `await`, `setTimeout`, `setImmediate`, and Promise chains
+- `EventContext` is not thread-safe — it's designed for single-event, single-async-chain use
+- The global singleton `AsyncLocalStorage` means all `@wooksjs/event-core` consumers in a process share context — version mismatches are caught at import time
+- `set()` writes to the first context in the parent chain where the key exists — if you need to shadow a parent value locally, use `setOwn()`
+- `get()` on a `Cached<T>` found in a parent returns the parent's cached value without re-computing — if you need a fresh local computation, use `getOwn()`
+- Parent chain traversal has O(depth) cost per lookup — keep chains shallow for performance