@yuhere/js-jsonrpc2 0.0.0-stage → 2.1.2

package/README.md

@@ -1,3 +1,278 @@
-# Temporary Holding Version
+# @yuhere/js-jsonrpc2
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A TypeScript JSON-RPC 2.0 server library with schema validation, authorization, dependency injection, and multiple transports.
+
+## Features
+
+### Deviations from the JSON-RPC 2.0 spec
+
+- **No named parameters.** `params` must be a positional array (or `null`).
+- **No notifications.** Every request must carry an `id`.
+- **No batch requests.** A batch payload is rejected with `INVALID_REQUEST`.
+
+### Extensions
+
+- **Permission checks.** Declare `grantTo` on a method and provide a `perm_check`
+  injectable; calls without permission fail with `PERMISSION_DENIED (-32604)`.
+- **`system.*` methods.** `system.listMethods`, `system.methodSignature`,
+  `system.methodHelp` are registered automatically.
+- **Global error transform.** Map arbitrary thrown errors to `RPCError` via the
+  `errorTransform` option.
+- **Streaming JSON serializer.** Responses are serialized with a streaming
+  stringifier that supports `Promise`, `Generator` / `AsyncGenerator`, and
+  `Buffer` (internal; not exported from the package root).
+
+## Install
+
+```shell
+npm install @yuhere/js-jsonrpc2
+```
+
+`express` is a peer dependency (v4 or v5). Node.js 18+ is required.
+
+## Quick start
+
+```ts
+import express from 'express';
+import { createRepository, createExpressRouter, s } from '@yuhere/js-jsonrpc2';
+
+const repository = createRepository({ withSystemMethods: true });
+
+repository.register(
+  {
+    namespace: 'add',
+    document: 'addition of 2 numbers',
+    signature: [s.number(), s.number(), s.number()],
+  },
+  (a: number, b: number) => a + b,
+);
+
+const app = express();
+app.use('/', createExpressRouter(repository, {}));
+app.listen(5000);
+```
+
+Calling it:
+
+```shell
+curl -s http://localhost:5000/ -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","method":"add","params":[1,2],"id":1}'
+# => {"jsonrpc":"2.0","id":1,"result":3}
+```
+
+## Registering methods
+
+`Repository.register(descriptor, handler)` takes a descriptor and a handler.
+The descriptor has three fields:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `namespace` | `string` | Method name (non-empty). |
+| `document` | `string \| (d) => string \| Promise<string>` | Optional help text for `system.methodHelp`. |
+| `grantTo` | `string[]` | Optional list of permissions required to call the method. |
+| `signature` | `[returnSchema, ...parameterSchema[]]` | Return type first, then parameters. |
+
+`signature[0]` is the return schema (`s.Schema` or `s.void()`).
+Every later slot is either a `s.Schema` (client-supplied) or
+`s.injectable(key)` (server-injected). Injectable slots may appear at any
+position except index `0`.
+
+```ts
+import { s } from '@yuhere/js-jsonrpc2';
+
+repository.register(
+  {
+    namespace: 'whoami',
+    document: 'returns the caller user agent',
+    signature: [
+      s.object({ userAgent: s.string().nullable() }),
+      s.injectable('request'),
+    ],
+  },
+  (req: { headers: Record<string, string> }) => ({
+    userAgent: req.headers['user-agent'] ?? null,
+  }),
+);
+```
+
+## Schemas
+
+Schemas are built with the `s` factory. They validate at runtime and derive
+TypeScript types.
+
+```ts
+s.string()                 // string
+s.string().min(1).max(64)  // length-constrained string
+s.number()                 // finite number
+s.boolean()                // boolean
+s.literal('2.0')           // exact literal
+s.array(s.string())        // string[]
+s.object({ id: s.number() })          // open object
+s.object({ id: s.number() }).strict() // all props required, no extras
+s.record(s.number())       // Record<string, number>
+s.union([s.string(), s.number()])
+s.tuple([s.string(), s.number()])
+s.enum(['pending', 'success', 'failed'])
+s.unknown()                // any JSON value
+s.void()                   // RPC-only: no return value
+s.injectable('request')    // RPC-only: server-injected parameter
+```
+
+Chainable modifiers: `.min()`, `.max()`, `.nullable()`, `.strict()`,
+`.describe(text)`. Validation: `.parse(input)` (throws
+`SchemaValidationError`) and `.safeParse(input)` (returns a result object).
+Introspection: `.toJSON()` returns a `SchemaDescription`.
+
+## Transports
+
+### Express
+
+```ts
+import { createExpressRouter } from '@yuhere/js-jsonrpc2';
+
+app.use('/', createExpressRouter(repository, {
+  bodyLimit: '1mb',
+  useHtdoc: true,
+  mkInjectable: (req, res, repo) => ({ request: req, response: res, repository: repo }),
+  errorTransform: (error) => /* return RPCError | undefined */ undefined,
+}));
+```
+
+The router handles `POST /` only. `useHtdoc` serves the bundled web UI
+(static assets under `htdoc/`).
+
+### WebSocket
+
+Attach to an existing HTTP server:
+
+```ts
+import { createServer } from 'node:http';
+import { attachWebSocket } from '@yuhere/js-jsonrpc2';
+
+const server = createServer(app);
+attachWebSocket(server, repository, {
+  path: '/',
+  mkInjectable: (ws, req, repo) => ({ socket: ws, request: req, repository: repo }),
+});
+server.listen(5000);
+```
+
+Or create a standalone server:
+
+```ts
+import { createWebSocketServer } from '@yuhere/js-jsonrpc2';
+
+const { server, wss, close } = await createWebSocketServer({
+  port: 8080,
+  host: '127.0.0.1',
+});
+```
+
+### stdio (NDJSON)
+
+```ts
+import { serveStdio } from '@yuhere/js-jsonrpc2';
+
+await serveStdio({ repository, framing: 'lines' });
+```
+
+`framing: 'lines'` reads one JSON value per line; `framing: 'json'` accepts
+concatenated JSON values.
+
+## Invoking directly
+
+`Repository.invoke(input, options?)` returns an `RPCResponse`
+(`RPCSuccess | RPCFailure`). Useful for tests or custom transports.
+
+```ts
+const response = await repository.invoke(
+  { jsonrpc: '2.0', method: 'add', params: [1, 2], id: 1 },
+  { injections: { request: fakeReq } },
+);
+```
+
+## Injectables
+
+An injectable factory is passed to the transport as `mkInjectable`. The
+resulting object is available to any signature slot declared as
+`s.injectable(key)`. Built-in defaults:
+
+| Transport | Default injectables |
+| --- | --- |
+| Express | `request`, `session`, `response`, `repository` |
+| WebSocket | `socket`, `request`, `repository` |
+| stdio | `repository`, `input`, `output` |
+
+Values may be plain values or functions; functions are awaited before
+injection.
+
+## Permission checks
+
+When a descriptor declares `grantTo`, the injected `perm_check(grantTo,
+descriptor)` is called:
+
+- returns `true` → allowed
+- returns an `RPCError` → re-thrown as-is
+- anything else → `PERMISSION_DENIED (-32604)`
+
+```ts
+app.use('/', createExpressRouter(repository, {
+  mkInjectable: (req, res, repo) => ({
+    request: req,
+    repository: repo,
+    perm_check: async (grantTo: string[]) => {
+      const roles = (req as any).session?.user?.roles ?? [];
+      return roles.some((r: string) => grantTo.includes(r));
+    },
+  }),
+}));
+```
+
+## Error transform
+
+`errorTransform(error)` may return an `RPCError` to override the default
+`INTERNAL_ERROR` mapping. Return `undefined` to fall back to the default
+behaviour. It is applied only to errors thrown by the method handler, not
+by request validation.
+
+```ts
+createExpressRouter(repository, {
+  errorTransform: (error) =>
+    error instanceof MyDomainError
+      ? new RPCError(-32000, 'Domain error', error.message)
+      : undefined,
+});
+```
+
+## Built-in methods
+
+| Method | Description |
+| --- | --- |
+| `system.listMethods` | Returns `string[]` of registered method names. |
+| `system.methodSignature` | Returns the schema list for a method. |
+| `system.methodHelp` | Returns the method's `document` (or `null`). |
+
+Disable them with `createRepository({ withSystemMethods: false })`.
+
+## Error codes
+
+| Code | Meaning |
+| --- | --- |
+| -32700 | Parse error |
+| -32600 | Invalid Request |
+| -32601 | Method not found |
+| -32602 | Invalid params |
+| -32603 | Internal error |
+| -32604 | Permission denied |
+| -32000..-32099 | Implementation-defined server errors |
+
+`codes` is exported from the package root:
+
+```ts
+import { codes } from '@yuhere/js-jsonrpc2';
+codes.INVALID_PARAMS; // -32602
+```
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: js-jsonrpc2
+description: Use when building or modifying a JSON-RPC 2.0 server with @yuhere/js-jsonrpc2 — registering methods with schema signatures, wiring the Express/WebSocket/stdio transport, streaming returns, or debugging params, permissions, and error mapping.
+---
+
+# @yuhere/js-jsonrpc2
+
+JSON-RPC 2.0 server middleware. Package name `@yuhere/js-jsonrpc2`. Node 18+.
+
+Hard constraints (by design, do not work around):
+
+- No named params. `params` MUST be a positional array or `null`.
+- No notifications. Every request MUST carry an `id`.
+- No batch. A batch payload returns `-32600 Invalid Request`.
+- No request-side streaming. Only method **return values** can be streamed.
+
+## Register a method
+
+1. Create the repository: `createRepository({ withSystemMethods: true })`.
+   Omit the option to get the same default. Pass `false` only to drop `system.*`.
+2. Call `repository.register(descriptor, handler)`.
+3. Set `descriptor.namespace` to a non-empty string.
+4. Set `descriptor.signature` to `[returnSchema, ...parameterSchema[]]`.
+   - `signature[0]` MUST be `s.Schema`, `s.void()`, or `s.stream(inner)`.
+     Never an injectable.
+   - Each later slot MUST be `s.Schema` (client param) or `s.injectable(key)`.
+5. Write `handler` so its positional args match the non-injectable slots in order;
+   injectable slots are filled at their declared positions.
+6. Use `s.*` factories for schemas: `s.string()`, `s.number()`, `s.boolean()`,
+   `s.literal(v)`, `s.array(item)`, `s.object(shape)`, `s.record(v)`,
+   `s.union([...])`, `s.tuple([...])`, `s.enum([...])`, `s.unknown()`.
+7. Chain modifiers before registering: `.min()`, `.max()`, `.nullable()`,
+   `.strict()`, `.describe(text)`.
+
+```ts
+import { createRepository, s } from '@yuhere/js-jsonrpc2';
+
+const repository = createRepository();
+repository.register(
+  { namespace: 'add', document: 'a + b', signature: [s.number(), s.number(), s.number()] },
+  (a: number, b: number) => a + b,
+);
+```
+
+## Stream a return value
+
+Declare `s.stream(inner)` as `signature[0]`. The handler MUST return an
+`AsyncGenerator`; anything else fails with `INTERNAL_ERROR` before any chunk is
+sent.
+
+1. Set `signature[0]` to `s.stream(inner)`. `inner` is any `s.Schema`
+   (including `s.unknown()`). No stream-of-stream, and `s.stream()` is not
+   valid in a parameter slot.
+2. Make the handler an `async function*` that yields values matching `inner`.
+3. Do NOT rely on `inner` for runtime chunk validation — chunks are **not**
+   validated. `inner` is documentation only; the WebUI uses it to render types.
+4. Expect frames of shape `RPCStreamChunk`, each a **complete** JSON-RPC-shaped
+   object (not nested under `result`):
+   `{ jsonrpc, id, done, index?, value?, error? }`.
+   - Normal data frame: `{ done: false, index, value }`.
+   - Normal end: `{ done: true, index }`.
+   - Mid-stream throw: `{ done: true, index?, error: { code, message } }`.
+   `id` is always the request id (never `null` for streams).
+5. The server yields exactly one terminal frame (`done: true`) per stream,
+   whether it finished normally or threw. A transport that receives the
+   terminal frame ends the response cleanly; it does not treat a terminal
+   `error` frame as a transport failure.
+6. Put cleanup in a `finally` inside the generator; the server calls
+   `source.return()` when the client disconnects, so `finally` runs.
+
+```ts
+repository.register(
+  {
+    namespace: 'logs.tail',
+    document: 'stream log lines',
+    signature: [s.stream(s.string()), s.string()],
+  },
+  async function* tail(path: string) {
+    for await (const line of follow(path)) yield line;
+  },
+);
+```
+
+Reference implementations for every stream shape (finite, infinite, throwing,
+empty, with injectables, `s.unknown()`) live in `dev/express.ts` under the
+`stream.*` namespace.
+
+## Wire a transport
+
+Pick exactly one transport per server process.
+
+- **Express**: call `app.use('/', createExpressRouter(repository, opts))`.
+  The router only handles `POST /`. Options: `mkInjectable`, `errorTransform`,
+  `bodyLimit`, `useHtdoc`, `streamFormat`.
+- **WebSocket on existing server**: call `attachWebSocket(server, repository, opts)`.
+  Options: `path`, `mkInjectable`, `errorTransform`, `allowOrigin`, `maxPayload`,
+  `onConnection`.
+- **Standalone WebSocket**: `await createWebSocketServer({ port, host })`;
+  it returns `{ server, wss, close() }`.
+- **stdio**: `await serveStdio({ repository, framing: 'lines' })`.
+  Use `framing: 'json'` for concatenated JSON values.
+
+All transports support stream returns.
+
+- Express emits one `RPCStreamChunk` per NDJSON line (`streamFormat: 'ndjson'`,
+  the default). `streamFormat: 'sse'` is reserved for `text/event-stream`;
+  currently the NDJSON path is the implemented one — do not depend on SSE
+  unless the transport source shows it.
+- WS and stdio emit one `RPCStreamChunk` per message/line.
+- Non-stream responses are serialized with a streaming JSON writer. If
+  serialization fails partway, the transport aborts the connection rather than
+  sending a truncated body with `200 OK`; if it fails before writing any byte,
+  the transport emits an `INTERNAL_ERROR` response instead.
+
+Supply `mkInjectable` when the handler needs request/socket context. Defaults:
+
+| Transport | Default injectables |
+| --- | --- |
+| Express | `request`, `session`, `response`, `repository` |
+| WebSocket | `socket`, `request`, `repository` |
+| stdio | `repository`, `input`, `output` |
+
+Injectable values may be plain values or functions; functions are awaited.
+
+## Enforce permissions
+
+1. Add `grantTo: ['role', ...]` to the descriptor.
+2. Inject `perm_check(grantTo, descriptor)` via `mkInjectable`.
+3. Return `true` to allow, return an `RPCError` to re-throw it verbatim, or
+   return anything else to get `PERMISSION_DENIED (-32604)`.
+4. Do not rely on `grantTo` alone — without `perm_check`, the check is skipped.
+
+## Map domain errors
+
+Call `errorTransform(error)` inside the transport options. Return an `RPCError`
+to override `INTERNAL_ERROR`, return `undefined` to fall back to the default.
+It applies only to errors thrown by the handler **before** streaming starts,
+not to request validation. Errors thrown **after** the first chunk has been
+sent cannot become `RPCFailure`; they surface as a `{ done: true, error }`
+terminal chunk instead.
+
+```ts
+createExpressRouter(repository, {
+  errorTransform: (e) => (e instanceof MyDomainError ? new RPCError(-32000, 'Domain', e.message) : undefined),
+});
+```
+
+## Invoke directly
+
+Call `repository.invoke(input, { injections?, errorTransform? })`. It returns
+`RPCResponse` (`RPCSuccess | RPCStreamSuccess | RPCFailure`) and never throws
+for protocol errors.
+
+For streaming methods the result is `RPCStreamSuccess`:
+`{ jsonrpc, id, chunks: AsyncGenerator<RPCStreamChunk> }`. It has no `result`
+and no boolean `stream` flag — branch on the presence of `chunks`:
+
+```ts
+const r = await repository.invoke(input);
+if ('chunks' in r) for await (const frame of r.chunks) { /* frame is RPCStreamChunk */ }
+else if ('error' in r) { /* RPCFailure */ }
+else { /* RPCSuccess, r.result */ }
+```
+
+Consume `chunks` yourself, or hand it to a transport. If a client disconnects
+mid-stream, the transport calls `chunks.return()`, which triggers the handler's
+`finally`.
+
+## Client (`webui`)
+
+`RpcClient.call<T>(method, ...params)` returns
+`CallResult<T> = Promise<T> | AsyncGenerator<T>`. It inspects the first
+frame: a `done` field means stream, otherwise the resolved value is the
+ordinary `result`. Use `isStreamResult(x)` to narrow.
+
+- `const r = await rpc.call('add', 1, 2)` → `r` is `3`.
+- `const r = await rpc.call('logs.tail', '/var/log/app.log')` → `r` is an
+  `AsyncGenerator`; `for await (const line of r) ...`.
+- HTTP transport calls `reader.cancel()` only on early exit (`break` / throw /
+  bad first frame), so the connection is aborted and the server's
+  `res.on('close')` fires. A clean read lets the connection return to the pool;
+  it does not cancel.
+- WS transport routes the first message via a one-shot waiter, then streams
+  subsequent frames per `id`.
+
+## Handle errors
+
+Read error codes from the exported `codes` object. `RPCError` carries
+`code`, `message`, `data`. Common codes: `-32700` parse, `-32600` invalid
+request, `-32601` method not found, `-32602` invalid params, `-32603` internal,
+`-32604` permission denied.
+
+For streams, a mid-stream `RPCError` becomes a terminal chunk with
+`error: { code, message }`; clients re-throw it as `RPCError`.
+
+## Use built-in methods
+
+Keep `withSystemMethods` on (default) to expose `system.listMethods`,
+`system.methodSignature`, `system.methodHelp`. Set `document` on a descriptor
+so `system.methodHelp` returns useful text.
+
+`system.methodSignature` reports a stream return as
+`{ kind: 'stream', children: { inner: <schema> } }`.
+
+## Common mistakes
+
+- **Passing named params or a bare object as `params`.** `convertParams` rejects
+  anything that is not an array or `null` with `INVALID_PARAMS`. Always send
+  `params: [...]`.
+- **Omitting `id`.** `RPCRequestSchema` requires it; the request fails with
+  `INVALID_REQUEST`. Notifications are not supported.
+- **Naming descriptor fields `sign` / `doc`.** The schema is strict; registration
+  throws `TypeError`. Use `signature` and `document`.
+- **Putting `s.injectable()` at `signature[0]`.** `buildDescriptor` throws; the
+  first slot is the return type.
+- **Forgetting `mkInjectable` for a `s.injectable(key)` slot.** `convertParams`
+  throws `INVALID_PARAMS` for the missing key.
+- **Expecting `errorTransform` to catch validation errors.** It only wraps the
+  handler call.
+- **Declaring `s.stream(inner)` but returning a plain value from the handler.**
+  The server throws `INTERNAL_ERROR` before sending any chunk.
+- **Expecting chunks to be validated against `inner`.** They are not. `inner`
+  is documentation only.
+- **Trying to stream `params`.** Not supported; only return values can stream.
+- **Nesting `s.stream()` inside `s.stream()` or inside a parameter slot.**
+  `s.stream()` is only valid at `signature[0]`.
+- **Forgetting `finally` in a streaming handler.** When the client disconnects
+  the server calls `source.return()`, so `finally` is the only place to close
+  DB cursors, files, etc.
+- **Calling `rpc.call()` and assuming `Promise`.** For stream methods it
+  resolves to an `AsyncGenerator`. Branch with `isStreamResult(r)`.
+- **Assuming stream frames are nested under `result` or carry a `stream: true`
+  flag.** Each frame is a complete `RPCStreamChunk` with `jsonrpc` and `id`.
+  Branch on `done` (and `error`), not on a wrapper field.
+- **Treating a terminal `error` frame as a broken connection.** A mid-stream
+  throw is delivered as `{ done: true, error }`; the HTTP/WS/stdio response
+  itself ends cleanly. Only transport-level failures abort the connection.

package/dist/cli/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli/cli.ts"],"names":[],"mappings":""}

package/dist/cli/cli.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// src/cli.ts
+//
+// `jsonrpc2-demo` 命令入口：启动带完整 demo 方法的 HTTP + WebSocket 服务，
+// 并自动打开 WebUI（默认 http://localhost:5000/）。
+//
+// 环境变量：
+//   PORT     监听端口（默认 5000；被占用时自动换随机端口）
+//   NO_OPEN  设为 1 时不自动打开浏览器
+//   HOST     监听地址（默认 0.0.0.0）
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import express from 'express';
+import { createRepository } from '../core/Repository';
+import { installDemoMethods } from './demo-methods';
+import { createExpressRouter } from '../transport/express';
+import { attachWebSocket } from '../transport/ws';
+const here = path.dirname(fileURLToPath(import.meta.url));
+function htdocDir() {
+    // dist/cli.js → 包根/htdoc
+    return path.resolve(here, '..', 'htdoc');
+}
+function openBrowser(url) {
+    let cmd;
+    let args;
+    if (process.platform === 'darwin') {
+        cmd = 'open';
+        args = [url];
+    }
+    else if (process.platform === 'win32') {
+        // start 的第一个参数会被当作窗口标题，传空字符串占位。
+        cmd = 'cmd';
+        args = ['/c', 'start', '""', url];
+    }
+    else {
+        cmd = 'xdg-open';
+        args = [url];
+    }
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => {
+            console.log(`(无法自动打开浏览器，请手动访问 ${url})`);
+        });
+        child.unref();
+    }
+    catch {
+        console.log(`(无法自动打开浏览器，请手动访问 ${url})`);
+    }
+}
+function listen(server, host, port) {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.off('listening', onListening);
+            if (err.code === 'EADDRINUSE' && port !== 0) {
+                console.warn(`端口 ${port} 已被占用，改用随机端口重试。`);
+                server.once('error', reject);
+                server.once('listening', onListening);
+                server.listen(0, host);
+                return;
+            }
+            reject(err);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            const addr = server.address();
+            const actual = typeof addr === 'object' && addr ? addr.port : port;
+            resolve(actual);
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, host);
+    });
+}
+async function main() {
+    const repository = createRepository({ withSystemMethods: true });
+    installDemoMethods(repository);
+    const app = express();
+    app.use('/', createExpressRouter(repository, { useHtdoc: true }));
+    const server = createServer(app);
+    attachWebSocket(server, repository, {
+        path: '/',
+        mkInjectable: (ws, req, repo) => ({
+            socket: ws,
+            request: req,
+            repository: repo,
+            requestId: `ws-${Math.random().toString(36).slice(2, 8)}`,
+        }),
+    });
+    const host = process.env['HOST'] ?? '0.0.0.0';
+    const requestedPort = Number(process.env['PORT'] ?? 5000);
+    const port = await listen(server, host, requestedPort);
+    const url = `http://localhost:${port}/`;
+    const wsUrl = `ws://localhost:${port}/`;
+    const hasWebUI = existsSync(path.join(htdocDir(), 'index.html'));
+    console.log('');
+    console.log('  js-jsonrpc2 demo');
+    console.log('  ────────────────────────────────────────');
+    console.log(`  HTTP  (POST /)     ${url}`);
+    console.log(`  WebSocket          ${wsUrl}`);
+    if (hasWebUI) {
+        console.log(`  WebUI              ${url}`);
+    }
+    else {
+        console.log('  WebUI              （未构建：请先运行 `npm run build:webui`）');
+    }
+    console.log('');
+    console.log('  按 Ctrl+C 停止。');
+    console.log('');
+    if (hasWebUI && process.env['NO_OPEN'] !== '1') {
+        openBrowser(url);
+    }
+    let shuttingDown = false;
+    const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log('\n正在关闭…');
+        server.close(() => process.exit(0));
+        // 兜底：3 秒内没关完就强退
+        setTimeout(() => process.exit(0), 3000).unref();
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+}
+main().catch((err) => {
+    console.error('启动失败：', err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli/cli.ts"],"names":[],"mappings":";AACA,aAAa;AACb,EAAE;AACF,2DAA2D;AAC3D,0CAA0C;AAC1C,EAAE;AACF,QAAQ;AACR,uCAAuC;AACvC,4BAA4B;AAC5B,8BAA8B;AAC9B,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,SAAS,QAAQ;IACb,yBAAyB;IACzB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,WAAW,CAAC,GAAW;IAC5B,IAAI,GAAW,CAAC;IAChB,IAAI,IAAc,CAAC;IACnB,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAChC,GAAG,GAAG,MAAM,CAAC;QACb,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACjB,CAAC;SAAM,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACtC,gCAAgC;QAChC,GAAG,GAAG,KAAK,CAAC;QACZ,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACtC,CAAC;SAAM,CAAC;QACJ,GAAG,GAAG,UAAU,CAAC;QACjB,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACjB,CAAC;IACD,IAAI,CAAC;QACD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACpE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACnB,OAAO,CAAC,GAAG,CAAC,oBAAoB,GAAG,GAAG,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,CAAC,GAAG,CAAC,oBAAoB,GAAG,GAAG,CAAC,CAAC;IAC5C,CAAC;AACL,CAAC;AAED,SAAS,MAAM,CACX,MAAuC,EACvC,IAAY,EACZ,IAAY;IAEZ,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACnC,MAAM,OAAO,GAAG,CAAC,GAA0B,EAAE,EAAE;YAC3C,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;YACrC,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;gBAC1C,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,iBAAiB,CAAC,CAAC;gBAC1C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;gBAC7B,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;gBACtC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;gBACvB,OAAO;YACX,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,CAAC;QAChB,CAAC,CAAC;QACF,MAAM,WAAW,GAAG,GAAG,EAAE;YACrB,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC7B,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACnE,OAAO,CAAC,MAAM,CAAC,CAAC;QACpB,CAAC,CAAC;QACF,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;QACtC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;AACP,CAAC;AAED,KAAK,UAAU,IAAI;IACf,MAAM,UAAU,GAAG,gBAAgB,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;IACjE,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAE/B,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,mBAAmB,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAElE,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IACjC,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE;QAChC,IAAI,EAAE,GAAG;QACT,YAAY,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;YAC9B,MAAM,EAAE,EAAE;YACV,OAAO,EAAE,GAAG;YACZ,UAAU,EAAE,IAAI;YAChB,SAAS,EAAE,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;SAC5D,CAAC;KACL,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC;IAC9C,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC;IAC1D,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;IAEvD,MAAM,GAAG,GAAG,oBAAoB,IAAI,GAAG,CAAC;IACxC,MAAM,KAAK,GAAG,kBAAkB,IAAI,GAAG,CAAC;IACxC,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC;IAEjE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAClC,OAAO,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC;IAC1D,OAAO,CAAC,GAAG,CAAC,wBAAwB,GAAG,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,wBAAwB,KAAK,EAAE,CAAC,CAAC;IAC7C,IAAI,QAAQ,EAAE,CAAC;QACX,OAAO,CAAC,GAAG,CAAC,wBAAwB,GAAG,EAAE,CAAC,CAAC;IAC/C,CAAC;SAAM,CAAC;QACJ,OAAO,CAAC,GAAG,CAAC,uDAAuD,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC9B,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAEhB,IAAI,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,GAAG,EAAE,CAAC;QAC7C,WAAW,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAED,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,MAAM,QAAQ,GAAG,GAAG,EAAE;QAClB,IAAI,YAAY;YAAE,OAAO;QACzB,YAAY,GAAG,IAAI,CAAC;QACpB,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACvB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,gBAAgB;QAChB,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;IACpD,CAAC,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACjC,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AACtC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACjB,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC5B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC,CAAC,CAAC"}

package/dist/cli/demo-methods.d.ts

@@ -0,0 +1,10 @@
+import type { Repository } from '../core/Repository';
+/**
+ * 注册一整套用于演示/调试的 RPC 方法。
+ * 覆盖：基础类型、字面量/枚举、数组/元组、对象、Record、联合、
+ * nullable、unknown、注入参数、各种返回形态、深层嵌套、混合大杂烩、流式返回。
+ *
+ * 被 dev/express.ts 与 src/cli.ts 共用。
+ */
+export declare function installDemoMethods(repository: Repository): void;
+//# sourceMappingURL=demo-methods.d.ts.map

package/dist/cli/demo-methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo-methods.d.ts","sourceRoot":"","sources":["../../src/cli/demo-methods.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAimB/D"}