@hile/context 3.0.1 → 3.0.2

package/AI.md

@@ -0,0 +1,154 @@
+# AI Guide For @hile/context
+
+
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+
+
+Purpose: Propagate request/work-unit context through async calls, models, micro messages, queues, and logger bindings.
+
+
+
+Use this file when an AI agent installs the npm package and needs package-local examples, package selection rules, boundaries, and verification steps.
+
+
+
+## Package Selection
+
+
+
+| User asks for | Use | Also read |
+|---|---|---|
+| Propagate request id, tenant id, logger bindings, or micro context | `@hile/context` | `packages/model-context.md` |
+
+
+
+# Model And Context
+
+Packages: `@hile/model`, `@hile/context`.
+
+## Use When
+
+Use `@hile/model` for reusable business logic and `@hile/context` for request/work-unit context that should flow through async calls, micro messages, and queue jobs.
+
+## Do Not Use When
+
+- Do not put business logic only in controllers when it will be reused by jobs, pages, or message handlers.
+- Do not add fixed business fields to `@hile/context`; each app owns its context shape.
+
+## Install
+
+```bash
+pnpm add @hile/model @hile/context
+```
+
+## Imports
+
+```ts
+import { defineModel, loadModel } from '@hile/model'
+import { contextHttp, contextModel, getContext, requireContext, runWithContext } from '@hile/context'
+```
+
+## Copy-Paste Example
+
+```ts
+import { defineModel } from '@hile/model'
+
+export default defineModel(async (input: { name: string }) => {
+  return { greeting: `Hello ${input.name}` }
+})
+```
+
+Use it:
+
+```ts
+const result = await loadModel(greetModel, { name: 'Ada' })
+```
+
+## More Examples
+
+```ts
+import { defineModel } from '@hile/model'
+import typeormService from '@hile/typeorm'
+
+export const findUser = defineModel({
+  services: [typeormService] as const,
+  pipelines: [
+    async (ctx, next) => {
+      if (!ctx.args.userId) throw new Error('userId is required')
+      await next()
+    },
+  ],
+  async main([ds], input: { userId: string }) {
+    return ds.getRepository(User).findOneBy({ id: input.userId })
+  },
+})
+```
+
+Context in HTTP:
+
+```ts
+http.use(contextHttp({
+  read: (ctx) => ({ requestId: String(ctx.headers['x-request-id'] ?? crypto.randomUUID()) }),
+  write: (context, ctx) => ctx.set('x-request-id', String(context.requestId ?? '')),
+}))
+```
+
+Context in model pipeline:
+
+```ts
+const withTenant = contextModel<{ tenantId: string }>({
+  read: (input) => ({ tenantId: input.tenantId }),
+})
+```
+
+## Compose With
+
+- `@hile/http` controllers should call `loadModel()`.
+- `@hile/redis-idempotency` and `@hile/redis-rate-limit` provide model pipeline middleware.
+- `@hile/micro` propagates context in message metadata.
+- `@hile/redis-stream-queue` snapshots context when enqueuing and restores it in workers.
+
+## Runtime And Lifecycle Notes
+
+- `loadModel(model, input)` rejects if the first argument was not created by `defineModel()`.
+- Model input must be an object.
+- Services are loaded in the order of the `services` tuple.
+- Pipeline middleware follows Koa-style `await next()`.
+- The terminal model result is stored in `ctx.state.result` and returned by `loadModel()`.
+- `runWithContext()` merges with parent context by default; pass `{ merge: false }` to replace.
+- `getContext()` returns a frozen shallow snapshot.
+- `requireContext(keys)` throws when selected keys are missing.
+
+## Anti-Patterns
+
+- Passing primitives to `loadModel()`.
+- Mutating context snapshots.
+- Logging whole context objects by default.
+- Assuming context propagation changes business payloads; it should stay in metadata or async storage.
+
+## Verification Checklist
+
+- Models export `defineModel(...)` results.
+- Controllers and pages call `loadModel(model, objectInput)`.
+- Pipeline middleware writes derived state to `ctx.state`.
+- Context keys are app-defined and JSON-serializable when crossing process boundaries.
+
+
+
+# Global Guardrails
+
+
+
+## Never Generate These Patterns
+
+- Do not call `loadService()` at module top level; it starts resources during import.
+- Do not default-export plain functions from `*.boot.*` files; `hile start` expects a Hile service.
+- Do not set `ctx.body` and also return a controller value.
+- Do not assume `@hile/http` Zod validation mutates or coerces `ctx.query`, `ctx.params`, or `ctx.request.body`.
+- Do not put reusable business logic only in controllers, pages, queue workers, or message handlers.
+- Do not use old message examples that append a secondary response getter; current request APIs return promises directly.
+- Do not claim exactly-once delivery or execution from Redis locks, queues, idempotency, or rate limits.
+- Do not use queue `jobId` as the only side-effect idempotency boundary.
+- Do not log the entire async context by default.

package/README.md

@@ -1,161 +1,56 @@
 # @hile/context
 
-Typed async context propagation primitives for Hile applications.
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-`@hile/context` does not define business fields. It stores whatever context shape the application declares and keeps that data isolated across async work. Adapters can seed context from HTTP, model pipelines, logger bindings, and `@hile/micro` calls without adding fields to business payloads.
+Propagate request/work-unit context through async calls, models, micro messages, queues, and logger bindings.
 
-## Install
-
-```bash
-pnpm add @hile/context
-```
-
-## Quick Start
-
-```typescript
-import { getContext, runWithContext } from '@hile/context'
-
-type AppContext = {
-  shopId: string
-  memberId: string
-  channel: 'web' | 'wechat'
-}
-
-await runWithContext<AppContext>({
-  shopId: 'shop-1',
-  memberId: 'member-1',
-  channel: 'web',
-}, async () => {
-  const context = getContext<AppContext>()
-  console.log(context.shopId)
-})
-```
-
-Outside `runWithContext()`, `getContext()` returns an empty object.
-
-## Core API
-
-### runWithContext(context, callback, options?)
-
-Runs `callback` inside an `AsyncLocalStorage` scope.
-
-```typescript
-await runWithContext<AppContext>({ shopId: 'shop-1' }, async () => {
-  await doWork()
-})
-```
-
-Nested calls merge with the parent context by default:
-
-```typescript
-await runWithContext<AppContext>({ shopId: 'shop-1', channel: 'web' }, async () => {
-  await runWithContext<AppContext>({ channel: 'wechat' }, async () => {
-    getContext<AppContext>() // { shopId: 'shop-1', channel: 'wechat' }
-  })
-})
-```
-
-Pass `{ merge: false }` to replace the parent context.
-
-### getContext()
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
 
-Returns a readonly shallow snapshot of the active context. Mutating the returned object does not mutate the store.
+## When To Use
 
-### snapshotContext()
+Use `@hile/model` for reusable business logic and `@hile/context` for request/work-unit context that should flow through async calls, micro messages, and queue jobs.
 
-Returns a readonly shallow snapshot for propagation. Cross-process transports should only put JSON-serializable values into context.
-
-### requireContext(keys)
-
-Asserts that selected application-defined keys are present.
-
-```typescript
-const context = requireContext<AppContext>(['shopId', 'channel'])
-```
-
-It throws `MissingContextError` when a selected key is missing.
-
-## HTTP Adapter
-
-`contextHttp()` is mapping-only. The package does not prescribe header names.
-
-```typescript
-import { contextHttp } from '@hile/context'
+## Install
 
-app.use(contextHttp<AppContext, Koa.Context>({
-  read: ctx => ({
-    shopId: ctx.get('x-shop'),
-    channel: ctx.get('x-channel') as AppContext['channel'],
-  }),
-  write: (context, ctx) => {
-    if (context.shopId) ctx.set('x-current-shop', context.shopId)
-  },
-}))
+```bash
+pnpm add @hile/context
 ```
 
-## Model Adapter
+## Copy-Paste Example
 
-```typescript
-import { contextModel, requireContextModel } from '@hile/context'
+```ts
 import { defineModel } from '@hile/model'
 
-const model = defineModel({
-  pipelines: [
-    contextModel<{ store: string; source: 'web' | 'wechat' }, AppContext>({
-      read: input => ({
-        shopId: input.store,
-        channel: input.source,
-      }),
-    }),
-    requireContextModel<{ store: string; source: 'web' | 'wechat' }, AppContext>(['shopId']),
-  ],
-  async main(input) {
-    return getContext<AppContext>()
-  },
-})
-```
-
-## Logger Binding
-
-Logger bindings are opt-in. Without `pick` or `map`, no context fields are logged.
-
-```typescript
-import { withContextLogger } from '@hile/context'
-
-const logger = withContextLogger<AppContext>(baseLogger, {
-  pick: ['shopId', 'channel'],
+export default defineModel(async (input: { name: string }) => {
+  return { greeting: `Hello ${input.name}` }
 })
-
-logger.info({ event: 'checkout' }, 'checkout created')
 ```
 
-## @hile/micro Propagation
+Use it:
 
-When `@hile/micro` depends on `@hile/context`, calls made inside `runWithContext()` propagate the current context through message metadata:
-
-```typescript
-await runWithContext<AppContext>({ shopId: 'shop-1', channel: 'web' }, async () => {
-  await app.call('inventory', '/reserve', { sku: 'sku-1' })
-})
+```ts
+const result = await loadModel(greetModel, { name: 'Ada' })
 ```
 
-The receiving handler can call `getContext<AppContext>()`. The business `data` payload remains unchanged; context travels separately in `metadata.context`.
-
 ## Boundaries
 
-- No field names are built into this package.
-- Context is a request/work-unit scope, not a process-level configuration store.
-- `getContext()` returns a shallow snapshot, not a deep clone.
-- Cross-process propagation should use JSON-serializable values.
-- Logger integration logs only fields selected by the application.
+- Do not put business logic only in controllers when it will be reused by jobs, pages, or message handlers.
+- Do not add fixed business fields to `@hile/context`; each app owns its context shape.
 
-## Testing
+- Passing primitives to `loadModel()`.
+- Mutating context snapshots.
+- Logging whole context objects by default.
+- Assuming context propagation changes business payloads; it should stay in metadata or async storage.
 
-```bash
-pnpm --filter @hile/context test
-pnpm --filter @hile/context build
-```
+## Verify
+
+- Models export `defineModel(...)` results.
+- Controllers and pages call `loadModel(model, objectInput)`.
+- Pipeline middleware writes derived state to `ctx.state`.
+- Context keys are app-defined and JSON-serializable when crossing process boundaries.
 
-## License
+## More Context
 
-MIT
+- `AI.md` in this package: full package-local AI guide.
+- Root `llms-full.txt`: full monorepo AI context.
+- Root `references/`: source files copied from `docs/ai`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/context",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Typed async context propagation primitives for Hile applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,7 +12,7 @@
   "files": [
     "dist",
     "README.md",
-    "SKILL.md"
+    "AI.md"
   ],
   "license": "MIT",
   "publishConfig": {
@@ -24,7 +24,7 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/model": "^3.0.1"
+    "@hile/model": "^3.0.2"
   },
-  "gitHead": "14b55afba0e9af80a782eaa84f6f48c1e66861a1"
+  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
 }

package/SKILL.md

@@ -1,40 +0,0 @@
----
-name: context
-description: Use when implementing typed async context propagation, request/work-unit context, HTTP context mapping, model pipeline context, logger context bindings, or @hile/micro context propagation.
----
-
-# Context
-
-Use `@hile/context` when a Hile app needs request/work-unit data to flow through async code and microservice calls without passing it through every function argument.
-
-## Core Rule
-
-Never bake business fields into the package. The library owns storage and propagation only; applications own the context shape.
-
-```typescript
-type AppContext = {
-  shopId: string
-  channel: 'web' | 'wechat'
-}
-
-await runWithContext<AppContext>({ shopId, channel }, async () => {
-  await doWork()
-})
-```
-
-## Design Boundaries
-
-- Core storage is an `AsyncLocalStorage<Record<string, unknown>>`.
-- `getContext()` and `snapshotContext()` return readonly shallow snapshots.
-- Nested `runWithContext()` calls merge by default; pass `{ merge: false }` to replace.
-- `requireContext(keys)` validates only keys selected by the application.
-- Do not add fixed fields like organization, user, or request dimensions to core types.
-- Cross-process propagation should use JSON-serializable context values.
-
-## Adapters
-
-- Use `contextHttp({ read, write })` to map arbitrary HTTP request/response details to and from context. The package must not prescribe header names.
-- Use `contextModel({ read })` inside `@hile/model` pipelines to seed context from model input.
-- Use `requireContextModel(keys)` to enforce selected application-owned keys inside model pipelines.
-- Use `withContextLogger(logger, { pick })` or `{ map }` to opt into logger bindings. Never log the whole context by default.
-- `@hile/micro` propagates context in `metadata.context`; business payloads remain unchanged.