feat: quality pass — logger, RPC retries, asyncapi resilience, docs

Core:
- Pluggable MqttLogger replaces internal console.* (drain timeout,
  validation, metric/error handler crashes); consoleLogger default,
  noopLogger for silence, app.getLogger() for plugins.
- app.request() gains retries / retryDelay; only retries on
  RpcTimeoutError so non-idempotent commands aren't multiplied.
- parseSharedSubscription() rejects NUL bytes, empty group, all-slash
  filter, and misplaced + / # wildcards.
- Export MqttPacket type alias with usage notes.

AsyncAPI:
- listen() errors wrap host:port; long-lived error listener attached
  after startup; startup log routed through app.getLogger().
- New test suites: builder, handlers, plugin, yaml.

zod:
- peerDependencies now declares @mqttkit/core (closes silent
  cross-version installs).

tsconfig:
- noImplicitOverride enabled.

Docs:
- New Logger guide (en + zh) under Production sidebar section.
- RPC page rewritten — documents retries/retryDelay, RpcTimeoutError,
  idempotency caveat, and the deliberate choice not to bundle p-retry.
- New custom-logger example + docs page.
- RPC example gains a flaky-downstream retry demo.
- Inlined CHANGELOG body into docs/changelog.md (drops root CHANGELOG).

Release tooling:
- scripts/publish.mjs now diffs local vs npm version per package,
  auto-skips in-sync packages, refuses to publish when local < npm,
  and adds --check / --force flags. New publish:status npm script
  (avoids bun's prepublish:check lifecycle clash).

Versions: @mqttkit/core 0.2.1 → 0.2.2, @mqttkit/asyncapi 0.2.0 → 0.2.1,
@mqttkit/zod 0.1.0 → 0.1.1. aedes and typebox unchanged.

Author: keyp-dev

CHANGELOG.md

@@ -60,6 +60,66 @@ const app = new MqttApp<{ principal?: { uid: string } }>()
 await app.listen()
 ```
 
+## App API at a glance
+
+The `MqttApp` builder methods covered in the quick start are listed below.
+Each returns `this`, so they chain.
+
+| Method | Purpose |
+| --- | --- |
+| `use(plugin \| middleware)` | Register a plugin (`router()`, broker adapter, …) or a global middleware. |
+| `decorate(key, value)` | Inject a service into `ctx.services` with type inference on the App generic. |
+| `on(eventName, handler)` | Observe broker lifecycle events (`client.connect`, `client.subscribe`, …). |
+| `onStart(hook)` / `onStop(hook)` | Run code after `listen()` succeeds or before `stop()` finishes. |
+| `onError(handler)` | App-level error sink — receives `{ error, topic, phase, route, ctx }`. |
+| `onMetric(handler)` | Structured per-dispatch / per-publish events for Prometheus / OTel. |
+| `onBeforePublish(hook)` | Mutate outbound `{ topic, payload, options }` (e.g. inject `traceparent`). |
+| `logger(logger)` | Forward mqttkit's internal warnings into pino / OpenTelemetry / Sentry. |
+| `addSchemaProvider(provider)` | Plug in non-Standard-Schema validators (e.g. raw TypeBox). |
+| `publish(topic, payload, opts?)` | Server-side outbound publish (also funnels through `onBeforePublish`). |
+| `request(topic, payload, opts?)` | MQTT 5 RPC with optional `retries` / `retryDelay`. |
+| `stop({ drain?, timeout? })` | Graceful shutdown — defaults to draining in-flight handlers. |
+
+### Error handling sketch
+
+```ts
+import { MqttApp, router } from '@mqttkit/core'
+
+const app = new MqttApp()
+  .use(adapter)
+  .onError(({ error, phase, topic }) => {
+    // phases: middleware | handler | validation | policy | publish | timeout | overload
+    sentry.captureException(error, { tags: { topic, phase } })
+  })
+  .use(
+    router().topic('devices/:uid/events', {
+      timeout: 1_000,
+      concurrency: 100,
+      onError: ({ error }) => metrics.routeFailures.inc(), // route-scoped, runs first
+      async onMessage(ctx) {
+        await doWork(ctx)
+      },
+    }),
+  )
+```
+
+### Custom logger
+
+```ts
+import { MqttApp, type MqttLogger } from '@mqttkit/core'
+import { pino } from 'pino'
+
+const log = pino({ name: 'mqttkit' })
+const logger: MqttLogger = {
+  debug: (msg, meta) => log.debug(meta, msg),
+  info: (msg, meta) => log.info(meta, msg),
+  warn: (msg, meta) => log.warn(meta, msg),
+  error: (msg, meta) => log.error(meta, msg),
+}
+
+new MqttApp().logger(logger)
+```
+
 ## Schema Validation
 
 `topic({ schema })` accepts any [Standard Schema](https://standardschema.dev/) validator (zod, valibot, arktype, …). The validated payload is exposed on `ctx.body` with full type inference.
@@ -89,7 +149,7 @@ See the [Getting Started guide](https://mqttkit.keyp.dev/getting-started) for ro
 
 ## Examples
 
-Runnable examples under [`examples/`](./examples) cover the basic TCP / WebSocket broker, lifecycle events, service push, Kafka bridge, schema validation, MQTT 5 RPC, AsyncAPI docs (standalone HTTP or shared Elysia port), and Prometheus metrics.
+Runnable examples under [`examples/`](./examples) cover the basic TCP / WebSocket broker, lifecycle events, service push, Kafka bridge, schema validation, MQTT 5 RPC (including `app.request({ retries, retryDelay })`), AsyncAPI docs (standalone HTTP or shared Elysia port), Prometheus metrics, and a custom JSON logger (`examples/custom-logger`).
 
 ```bash
 bun install
@@ -103,3 +163,19 @@ bun run test
 bun run typecheck
 bun run build
 ```
+
+## Releasing
+
+`scripts/publish.mjs` compares each package's local version against the npm registry and only publishes packages whose local version is ahead (or not on npm yet). Packages already in sync are silently skipped.
+
+```bash
+bun run publish:status      # report local vs npm without publishing
+bun run publish:dry-run     # dry-run the actual publish flow
+bun run publish:packages    # publish whatever needs publishing
+
+# Single package by name (still subject to the version-ahead check)
+bun run publish:core
+
+# Bypass the check (rarely needed)
+node scripts/publish.mjs --force
+```

README.md

@@ -60,6 +60,65 @@ const app = new MqttApp<{ principal?: { uid: string } }>()
 await app.listen()
 ```
 
+## App API 一览
+
+下列方法都返回 `this`，可以链式调用：
+
+| 方法 | 用途 |
+| --- | --- |
+| `use(plugin \| middleware)` | 注册 plugin（`router()`、broker 适配器…）或全局 middleware。 |
+| `decorate(key, value)` | 把服务注入 `ctx.services`，类型推断会沿用到 App 泛型。 |
+| `on(eventName, handler)` | 监听 broker lifecycle event（`client.connect`、`client.subscribe`…）。 |
+| `onStart(hook)` / `onStop(hook)` | `listen()` 成功后或 `stop()` 之前运行的钩子。 |
+| `onError(handler)` | 应用级错误漏斗——接收 `{ error, topic, phase, route, ctx }`。 |
+| `onMetric(handler)` | 每次 dispatch / publish 完成时发结构化指标，对接 Prometheus / OTel。 |
+| `onBeforePublish(hook)` | 出站发布前修改 `{ topic, payload, options }`（例如注入 `traceparent`）。 |
+| `logger(logger)` | 把 mqttkit 内部告警导入 pino / OpenTelemetry / Sentry 管线。 |
+| `addSchemaProvider(provider)` | 注册非 Standard-Schema 的校验器（如裸 TypeBox）。 |
+| `publish(topic, payload, opts?)` | 服务端主动发布（同样走 `onBeforePublish`）。 |
+| `request(topic, payload, opts?)` | MQTT 5 RPC，支持 `retries` / `retryDelay`。 |
+| `stop({ drain?, timeout? })` | 优雅停机——默认会等 in-flight handler 排空。 |
+
+### 错误处理示例
+
+```ts
+import { MqttApp, router } from '@mqttkit/core'
+
+const app = new MqttApp()
+  .use(adapter)
+  .onError(({ error, phase, topic }) => {
+    // phase 取值: middleware | handler | validation | policy | publish | timeout | overload
+    sentry.captureException(error, { tags: { topic, phase } })
+  })
+  .use(
+    router().topic('devices/:uid/events', {
+      timeout: 1_000,
+      concurrency: 100,
+      onError: ({ error }) => metrics.routeFailures.inc(), // 路由级，先于应用级运行
+      async onMessage(ctx) {
+        await doWork(ctx)
+      },
+    }),
+  )
+```
+
+### 自定义 logger
+
+```ts
+import { MqttApp, type MqttLogger } from '@mqttkit/core'
+import { pino } from 'pino'
+
+const log = pino({ name: 'mqttkit' })
+const logger: MqttLogger = {
+  debug: (msg, meta) => log.debug(meta, msg),
+  info: (msg, meta) => log.info(meta, msg),
+  warn: (msg, meta) => log.warn(meta, msg),
+  error: (msg, meta) => log.error(meta, msg),
+}
+
+new MqttApp().logger(logger)
+```
+
 ## Schema 校验
 
 `topic({ schema })` 接受任意 [Standard Schema](https://standardschema.dev/) 校验器（zod、valibot、arktype 等）。校验后的 payload 暴露在 `ctx.body` 上，并自动推断类型。
@@ -89,7 +148,7 @@ router、middleware、events、RPC、Kafka 桥接等详见 [快速开始](https:
 
 ## 示例
 
-[`examples/`](./examples) 下有可运行示例：TCP / WebSocket broker、lifecycle events、service push、Kafka bridge、schema 校验、MQTT 5 RPC、AsyncAPI 文档（独立 HTTP 或与 Elysia 复用端口）、Prometheus 指标。
+[`examples/`](./examples) 下有可运行示例：TCP / WebSocket broker、lifecycle events、service push、Kafka bridge、schema 校验、MQTT 5 RPC（含 `app.request({ retries, retryDelay })`）、AsyncAPI 文档（独立 HTTP 或与 Elysia 复用端口）、Prometheus 指标，以及自定义 JSON logger（`examples/custom-logger`）。
 
 ```bash
 bun install
@@ -103,3 +162,19 @@ bun run test
 bun run typecheck
 bun run build
 ```
+
+## 发布
+
+`scripts/publish.mjs` 会把每个包的本地版本和 npm registry 比较，**只发布**本地版本领先（或 npm 上还不存在）的包；已经同步的包会被静默跳过。
+
+```bash
+bun run publish:status      # 仅打印 local vs npm 状态，不发布
+bun run publish:dry-run     # 跑一次 dry-run 流水线
+bun run publish:packages    # 发布所有需要发布的包
+
+# 指定单个包（同样会先做版本检查）
+bun run publish:core
+
+# 跳过检查强制发布（一般用不到）
+node scripts/publish.mjs --force
+```