@zero-server/grpc 0.9.6 → 0.9.8

package/index.d.ts

@@ -1,2 +1,2 @@
-// AUTO-GENERATED by .tools/generate-package-stubs.js — edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
+// AUTO-GENERATED by .tools/generate-package-stubs.js - edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
 export * from './types/grpc';

package/index.js

@@ -1,4 +1,4 @@
-// AUTO-GENERATED by .tools/generate-package-stubs.js — edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
+// AUTO-GENERATED by .tools/generate-package-stubs.js - edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
 'use strict';
 const lib = require("./lib/grpc");
 

package/lib/debug.js

@@ -16,7 +16,7 @@
  *   log.error('failed to connect', err);
  *   log('shorthand for debug level');
  *
- *   // Set minimum level — anything below is silenced
+ *   // Set minimum level - anything below is silenced
  *   debug.level('warn');   // only warn, error, fatal
  *   debug.level('silent'); // suppress all output
  *   debug.level('trace');  // show everything
@@ -81,7 +81,7 @@ _enabledPatterns = _parsePatterns();
  */
 function _isEnabled(ns)
 {
-    if (!_enabledPatterns) return true; // No DEBUG set — enable all
+    if (!_enabledPatterns) return true; // No DEBUG set - enable all
     let enabled = false;
     for (const { neg, re } of _enabledPatterns)
     {
@@ -116,7 +116,7 @@ function _ts()
 }
 
 /**
- * Format arguments (like console.log — supports %s, %d, %j, %o).
+ * Format arguments (like console.log - supports %s, %d, %j, %o).
  * @private
  */
 function _format(args)
@@ -278,13 +278,13 @@ function debug(namespace)
  * Messages below this level are silenced.
  *
  * @param {string|number} level - Level name or number.
- *   `'trace'` (0) — all output
- *   `'debug'` (1) — debug and above
- *   `'info'` (2) — info and above
- *   `'warn'` (3) — warn and above
- *   `'error'` (4) — error and fatal only
- *   `'fatal'` (5) — fatal only
- *   `'silent'` (6) — nothing
+ *   `'trace'` (0) - all output
+ *   `'debug'` (1) - debug and above
+ *   `'info'` (2) - info and above
+ *   `'warn'` (3) - warn and above
+ *   `'error'` (4) - error and fatal only
+ *   `'fatal'` (5) - fatal only
+ *   `'silent'` (6) - nothing
  */
 debug.level = function(level)
 {

package/lib/grpc/call.js

@@ -4,10 +4,10 @@
  *              Wraps HTTP/2 streams with protobuf encode/decode, metadata,
  *              framing, deadline enforcement, and cancellation support.
  *
- *              - `UnaryCall` — single request, single response
- *              - `ServerStreamCall` — single request, stream of responses
- *              - `ClientStreamCall` — stream of requests, single response
- *              - `BidiStreamCall` — bidirectional streaming
+ *              - `UnaryCall` - single request, single response
+ *              - `ServerStreamCall` - single request, stream of responses
+ *              - `ClientStreamCall` - stream of requests, single response
+ *              - `BidiStreamCall` - bidirectional streaming
  *
  * @example | Unary handler
  *   async function GetUser(call) {
@@ -181,7 +181,7 @@ class BaseCall extends EventEmitter
 
         if (!this._headersSent)
         {
-            // Trailers-Only response — include status in initial HEADERS frame
+            // Trailers-Only response - include status in initial HEADERS frame
             this._headersSent = true;
             try
             {
@@ -199,7 +199,7 @@ class BaseCall extends EventEmitter
         }
         else
         {
-            // Headers already sent — send trailing HEADERS after final DATA
+            // Headers already sent - send trailing HEADERS after final DATA
             this.stream.on('wantTrailers', () =>
             {
                 try { this.stream.sendTrailers(trailHeaders); }
@@ -359,7 +359,7 @@ class BaseCall extends EventEmitter
 // -- Unary Call --------------------------------------------
 
 /**
- * A unary gRPC call — single request message, single response message.
+ * A unary gRPC call - single request message, single response message.
  *
  * @class
  * @extends BaseCall
@@ -391,7 +391,7 @@ class UnaryCall extends BaseCall
     }
 
     /**
-     * Initialize the call — collect the full request body and decode it.
+     * Initialize the call - collect the full request body and decode it.
      * @private
      * @returns {Promise<void>}
      */
@@ -422,7 +422,7 @@ class UnaryCall extends BaseCall
 // -- Server Streaming Call ---------------------------------
 
 /**
- * A server-streaming gRPC call — single request, multiple responses.
+ * A server-streaming gRPC call - single request, multiple responses.
  * The handler calls `call.write(msg)` for each response and `call.end()` to finish.
  *
  * @class
@@ -481,7 +481,7 @@ class ServerStreamCall extends BaseCall
 // -- Client Streaming Call ---------------------------------
 
 /**
- * A client-streaming gRPC call — multiple requests, single response.
+ * A client-streaming gRPC call - multiple requests, single response.
  * The handler iterates `for await (const msg of call)` to consume messages,
  * then returns the response object.
  *
@@ -512,7 +512,7 @@ class ClientStreamCall extends BaseCall
     }
 
     /**
-     * Initialize — set up the frame parser to enqueue decoded messages.
+     * Initialize - set up the frame parser to enqueue decoded messages.
      * @private
      */
     _init()
@@ -560,7 +560,7 @@ class ClientStreamCall extends BaseCall
     }
 
     /**
-     * Async iterator — enables `for await (const msg of call)`.
+     * Async iterator - enables `for await (const msg of call)`.
      *
      * @returns {AsyncIterator<object>}
      */
@@ -589,7 +589,7 @@ class ClientStreamCall extends BaseCall
 // -- Bidirectional Streaming Call ---------------------------
 
 /**
- * A bidirectional streaming gRPC call — multiple requests AND multiple responses.
+ * A bidirectional streaming gRPC call - multiple requests AND multiple responses.
  * The handler can `for await` incoming messages while simultaneously
  * calling `call.write()` to send responses.
  *
@@ -673,7 +673,7 @@ class BidiStreamCall extends BaseCall
     }
 
     /**
-     * Async iterator — enables `for await (const msg of call)`.
+     * Async iterator - enables `for await (const msg of call)`.
      *
      * @returns {AsyncIterator<object>}
      */

package/lib/grpc/client.js

@@ -266,7 +266,7 @@ class GrpcClient extends EventEmitter
     // -- Unary Call -----------------------------------------
 
     /**
-     * Make a unary gRPC call — send one message, receive one response.
+     * Make a unary gRPC call - send one message, receive one response.
      *
      * @param {string} methodName - RPC method name as defined in the proto service.
      * @param {object} request - Request message object.
@@ -394,7 +394,7 @@ class GrpcClient extends EventEmitter
     // -- Server Streaming ----------------------------------
 
     /**
-     * Make a server-streaming gRPC call — send one request, receive a stream of responses.
+     * Make a server-streaming gRPC call - send one request, receive a stream of responses.
      * Returns an async-iterable that yields decoded response messages.
      *
      * @param {string} methodName - RPC method name.
@@ -509,7 +509,7 @@ class GrpcClient extends EventEmitter
     // -- Client Streaming ----------------------------------
 
     /**
-     * Make a client-streaming gRPC call — send a stream of requests, receive one response.
+     * Make a client-streaming gRPC call - send a stream of requests, receive one response.
      * Returns a writable object with `write()`, `end()`, and a `response` Promise.
      *
      * @param {string} methodName - RPC method name.
@@ -608,7 +608,7 @@ class GrpcClient extends EventEmitter
     // -- Bidirectional Streaming ----------------------------
 
     /**
-     * Make a bidirectional streaming gRPC call — send and receive streams simultaneously.
+     * Make a bidirectional streaming gRPC call - send and receive streams simultaneously.
      * Returns an object that is both writable (`write`/`end`) and async-iterable.
      *
      * @param {string} methodName - RPC method name.

package/lib/grpc/codec.js

@@ -76,7 +76,7 @@ const TYPE_INFO = {
 // -- Writer ------------------------------------------------
 
 /**
- * Protobuf binary writer — encodes JavaScript objects into wire-format bytes.
+ * Protobuf binary writer - encodes JavaScript objects into wire-format bytes.
  *
  * @class
  *
@@ -397,7 +397,7 @@ class Writer
 // -- Reader ------------------------------------------------
 
 /**
- * Protobuf binary reader — decodes wire-format bytes into JavaScript values.
+ * Protobuf binary reader - decodes wire-format bytes into JavaScript values.
  *
  * @class
  *
@@ -762,7 +762,7 @@ class Reader
 function encode(obj, messageDesc, allMessages, depth = 0)
 {
     if (depth > MAX_RECURSION_DEPTH)
-        throw new Error(`Maximum encoding depth (${MAX_RECURSION_DEPTH}) exceeded — possible circular reference`);
+        throw new Error(`Maximum encoding depth (${MAX_RECURSION_DEPTH}) exceeded - possible circular reference`);
 
     if (!obj || typeof obj !== 'object')
         return Buffer.alloc(0);
@@ -809,7 +809,7 @@ function encode(obj, messageDesc, allMessages, depth = 0)
 function decode(buffer, messageDesc, allMessages, depth = 0)
 {
     if (depth > MAX_RECURSION_DEPTH)
-        throw new Error(`Maximum decoding depth (${MAX_RECURSION_DEPTH}) exceeded — possible circular reference`);
+        throw new Error(`Maximum decoding depth (${MAX_RECURSION_DEPTH}) exceeded - possible circular reference`);
 
     if (!Buffer.isBuffer(buffer) || buffer.length === 0)
         return _defaultObject(messageDesc);
@@ -830,7 +830,7 @@ function decode(buffer, messageDesc, allMessages, depth = 0)
 
         if (!field)
         {
-            // Unknown field — skip it (forward compatibility)
+            // Unknown field - skip it (forward compatibility)
             reader.skipField(wireType);
             continue;
         }
@@ -868,7 +868,7 @@ function _encodeField(writer, field, value, allMessages, depth)
 
     if (typeInfo)
     {
-        // Scalar type — skip default values in proto3
+        // Scalar type - skip default values in proto3
         if (_isDefaultValue(field.type, value)) return;
 
         writer.writeTag(field.number, typeInfo.wire);
@@ -913,7 +913,7 @@ function _encodeRepeated(writer, field, values, allMessages, depth)
     }
     else
     {
-        // Non-packable (strings, bytes, messages) — one tag per element
+        // Non-packable (strings, bytes, messages) - one tag per element
         for (const v of values) _encodeField(writer, field, v, allMessages, depth);
     }
 }

package/lib/grpc/credentials.js

@@ -5,7 +5,7 @@
  *              and metadata-based credentials. Supports certificate rotation
  *              and credential composition.
  *
- *              Uses only Node.js built-in `tls` and `fs` — no external packages.
+ *              Uses only Node.js built-in `tls` and `fs` - no external packages.
  *
  * @example | Insecure (plaintext)
  *   const { ChannelCredentials, GrpcClient } = require('@zero-server/sdk');
@@ -71,7 +71,7 @@ class ChannelCredentials
 
     /**
      * Create insecure (plaintext) credentials.
-     * No TLS — suitable for development or service-mesh environments
+     * No TLS - suitable for development or service-mesh environments
      * where transport security is handled by the infrastructure.
      *
      * @returns {ChannelCredentials}

package/lib/grpc/frame.js

@@ -23,7 +23,7 @@ const log = require('../debug')('zero:grpc');
 const FRAME_HEADER_SIZE = 5;
 
 /**
- * Maximum frame size (16 MB — matches the default gRPC max).
+ * Maximum frame size (16 MB - matches the default gRPC max).
  * @type {number}
  */
 const MAX_FRAME_SIZE = 16 * 1024 * 1024;
@@ -92,7 +92,7 @@ function _buildFrame(payload, flag)
 // -- Frame Decoder -----------------------------------------
 
 /**
- * Stateful gRPC frame parser — buffers incoming data and emits complete
+ * Stateful gRPC frame parser - buffers incoming data and emits complete
  * decompressed messages.  Designed to be fed chunks from an HTTP/2 stream.
  *
  * @class

package/lib/grpc/health.js

@@ -193,7 +193,7 @@ class HealthService
     }
 
     /**
-     * Handle a Check RPC — unary request for current health of a service.
+     * Handle a Check RPC - unary request for current health of a service.
      * @param {import('./call').UnaryCall} call
      */
     Check(call)
@@ -205,7 +205,7 @@ class HealthService
     }
 
     /**
-     * Handle a Watch RPC — server-stream that pushes status changes.
+     * Handle a Watch RPC - server-stream that pushes status changes.
      * Sends the current status immediately, then pushes on every change.
      * @param {import('./call').ServerStreamCall} call
      */
@@ -232,7 +232,7 @@ class HealthService
 
     /**
      * Get the schema object needed for server registration.
-     * Avoids requiring proto parsing — returns descriptors directly.
+     * Avoids requiring proto parsing - returns descriptors directly.
      * @returns {object} Schema compatible with GrpcServiceRegistry.addService
      */
     getSchema()

package/lib/grpc/index.js

@@ -1,6 +1,6 @@
 /**
  * @module grpc
- * @description Full gRPC support for zero-server — zero external dependencies.
+ * @description Full gRPC support for zero-server - zero external dependencies.
  *              Provides a proto3 parser, protobuf codec, gRPC framing, call objects,
  *              a service server, and a client for all four RPC patterns.
  *
@@ -14,7 +14,7 @@
  *              - Graceful shutdown with call draining
  *              - Message size limits and deadline enforcement
  *
- * @example | Quick Start — Server
+ * @example | Quick Start - Server
  *   const { createApp, parseProto } = require('@zero-server/sdk');
  *   const app = createApp();
  *   const schema = parseProto(`
@@ -35,7 +35,7 @@
  *
  *   app.listen(50051, { http2: true });
  *
- * @example | Quick Start — Client
+ * @example | Quick Start - Client
  *   const { GrpcClient, parseProto } = require('@zero-server/sdk');
  *   const schema = parseProto(fs.readFileSync('hello.proto', 'utf8'));
  *   const client = new GrpcClient('http://localhost:50051', schema, 'Greeter');

package/lib/grpc/metadata.js

@@ -1,6 +1,6 @@
 /**
  * @module grpc/metadata
- * @description gRPC metadata container — typed key-value pairs transmitted as
+ * @description gRPC metadata container - typed key-value pairs transmitted as
  *              HTTP/2 headers (initial metadata) and trailers (trailing metadata).
  *              Keys ending in `-bin` carry binary values (base64-encoded on the wire).
  *              All other keys carry ASCII string values.
@@ -44,7 +44,7 @@ const GRPC_INTERNAL = new Set([
 const MAX_KEY_LENGTH = 256;
 
 /**
- * Maximum total metadata size in bytes (soft limit — 8 KB default, configurable).
+ * Maximum total metadata size in bytes (soft limit - 8 KB default, configurable).
  * @type {number}
  */
 const DEFAULT_MAX_METADATA_SIZE = 8192;
@@ -52,7 +52,7 @@ const DEFAULT_MAX_METADATA_SIZE = 8192;
 // -- Metadata Class ----------------------------------------
 
 /**
- * gRPC metadata container — type-safe key-value pairs for headers and trailers.
+ * gRPC metadata container - type-safe key-value pairs for headers and trailers.
  *
  * @class
  *

package/lib/grpc/proto.js

@@ -1,6 +1,6 @@
 /**
  * @module grpc/proto
- * @description Zero-dependency proto3 parser — reads `.proto` file text and produces
+ * @description Zero-dependency proto3 parser - reads `.proto` file text and produces
  *              message descriptors, enum definitions, and service/RPC declarations
  *              that the codec and server use at runtime.
  *
@@ -17,9 +17,9 @@
  * @example
  *   const { parseProto } = require('./proto');
  *   const schema = parseProto(fs.readFileSync('chat.proto', 'utf8'));
- *   // schema.messages  — { MessageName: { fields: [...] } }
- *   // schema.enums     — { EnumName: { values: { ... } } }
- *   // schema.services  — { ServiceName: { methods: { ... } } }
+ *   // schema.messages  - { MessageName: { fields: [...] } }
+ *   // schema.enums     - { EnumName: { values: { ... } } }
+ *   // schema.services  - { ServiceName: { methods: { ... } } }
  */
 
 const fs = require('fs');
@@ -254,7 +254,7 @@ function parseProto(source, opts = {})
         {
             next(); expect('='); schema.syntax = next().value; expect(';');
             if (schema.syntax !== 'proto3')
-                log.warn('proto file uses syntax "%s" — only proto3 is fully supported', schema.syntax);
+                log.warn('proto file uses syntax "%s" - only proto3 is fully supported', schema.syntax);
         }
         else if (tok.value === 'package')
         {

package/lib/grpc/reflection.js

@@ -54,7 +54,7 @@ function buildFileDescriptorProto(schema, filename)
     // field 2: package (string)
     if (schema.package) w.string(2, schema.package);
 
-    // field 3: dependency (repeated string) — imported file names
+    // field 3: dependency (repeated string) - imported file names
     if (schema.imports)
     {
         for (const imp of schema.imports)
@@ -191,7 +191,7 @@ function _buildFieldDescriptorProto(field, schema)
     // field 9: oneof_index (if in a oneof)
     if (field.oneofName !== undefined)
     {
-        // Will use the index from the parent — simplified to 0 for now
+        // Will use the index from the parent - simplified to 0 for now
         w.int32(9, 0);
     }
 

package/lib/grpc/server.js

@@ -130,7 +130,7 @@ class GrpcServiceRegistry
         {
             if (!handlers[methodName])
             {
-                log.warn('no handler for %s/%s — will return UNIMPLEMENTED', serviceName, methodName);
+                log.warn('no handler for %s/%s - will return UNIMPLEMENTED', serviceName, methodName);
             }
 
             const routePath = pathPrefix + '/' + methodName;
@@ -178,7 +178,7 @@ class GrpcServiceRegistry
         const contentType = headers['content-type'] || '';
         if (!contentType.startsWith('application/grpc'))
         {
-            return false; // Not a gRPC request — let the normal HTTP pipeline handle it
+            return false; // Not a gRPC request - let the normal HTTP pipeline handle it
         }
 
         const grpcPath = headers[':path'];
@@ -290,7 +290,7 @@ class GrpcServiceRegistry
     }
 
     /**
-     * Begin draining — reject new calls and wait for active calls to finish.
+     * Begin draining - reject new calls and wait for active calls to finish.
      *
      * @param {number} [timeout=30000] - Maximum time to wait in ms.
      * @returns {Promise<void>}

package/lib/grpc/status.js

@@ -25,7 +25,7 @@ const GrpcStatus = {
     OK: 0,
     /** The operation was cancelled (typically by the caller). */
     CANCELLED: 1,
-    /** Unknown error — a catch-all for unexpected failures. */
+    /** Unknown error - a catch-all for unexpected failures. */
     UNKNOWN: 2,
     /** The client specified an invalid argument. */
     INVALID_ARGUMENT: 3,
@@ -47,7 +47,7 @@ const GrpcStatus = {
     OUT_OF_RANGE: 11,
     /** The operation is not implemented or not supported. */
     UNIMPLEMENTED: 12,
-    /** Internal error — invariants expected by the server have been broken. */
+    /** Internal error - invariants expected by the server have been broken. */
     INTERNAL: 13,
     /** The service is currently unavailable, usually a transient condition. */
     UNAVAILABLE: 14,

package/lib/grpc/watch.js

@@ -4,7 +4,7 @@
  *              Watches `.proto` files for changes using `fs.watch()` and
  *              re-parses/re-registers gRPC services automatically.
  *
- *              **Dev-only** — disabled by default when `NODE_ENV=production`.
+ *              **Dev-only** - disabled by default when `NODE_ENV=production`.
  *
  * @example
  *   const { createApp, watchProto } = require('@zero-server/sdk');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zero-server/grpc",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "description": "gRPC server, client, codec, framing, status, metadata, health, reflection, balancer.",
   "keywords": [
     "zero-server",
@@ -45,7 +45,7 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@zero-server/sdk": ">=0.9.6"
+    "@zero-server/sdk": ">=0.9.8"
   },
   "peerDependenciesMeta": {
     "@zero-server/sdk": {

package/types/body.d.ts

@@ -1,14 +1,82 @@
-// Re-exports for @zero-server/body — body parser types
-export {
-    BodyParserOptions,
-    JsonParserOptions,
-    UrlencodedParserOptions,
-    TextParserOptions,
-    MultipartOptions,
-    MultipartFile,
-    json,
-    urlencoded,
-    text,
-    raw,
-    multipart,
-} from './middleware';
+// TypeScript declarations for the bundled body parsers
+// (`json`, `urlencoded`, `text`, `raw`, `multipart`).
+//
+// These live in `lib/body/*` at runtime and are surfaced both via the
+// top-level SDK and the standalone `@zero-server/body` scope.  They are
+// declared here (not in `./middleware`) so the body-parser package has
+// a self-contained declaration file.
+
+import { MiddlewareFunction } from './middleware';
+import { Request } from './request';
+import { Response } from './response';
+
+export interface BodyParserOptions {
+    /** Max body size (e.g. '10kb', '1mb'). Default: '1mb'. */
+    limit?: string | number;
+    /** Content-Type(s) to match. Accepts a string, an array of strings, or a predicate function. */
+    type?: string | string[] | ((ct: string) => boolean);
+    /** Reject non-HTTPS requests with 403. */
+    requireSecure?: boolean;
+    /**
+     * Verification callback invoked with the raw buffer before parsing.
+     * Throw an error to reject the request with 403.
+     * Useful for webhook signature verification (e.g. Stripe, GitHub).
+     */
+    verify?: (req: Request, res: Response, buf: Buffer, encoding: string) => void;
+    /** Decompress gzip/deflate/br request bodies. Default: true. When false, compressed bodies return 415. */
+    inflate?: boolean;
+}
+
+export interface JsonParserOptions extends BodyParserOptions {
+    /** JSON.parse reviver function. */
+    reviver?: (key: string, value: any) => any;
+    /** Reject non-object/array roots. Default: true. */
+    strict?: boolean;
+}
+
+export interface UrlencodedParserOptions extends BodyParserOptions {
+    /** Enable nested bracket parsing. Default: false. */
+    extended?: boolean;
+    /** Max number of parameters. Default: 1000. Prevents parameter flooding DoS. */
+    parameterLimit?: number;
+    /** Max nesting depth for bracket syntax. Default: 32. Prevents deep-nesting DoS. */
+    depth?: number;
+}
+
+export interface TextParserOptions extends BodyParserOptions {
+    /** Fallback character encoding when Content-Type has no charset. Default: 'utf8'. */
+    encoding?: BufferEncoding;
+}
+
+export interface MultipartOptions {
+    /** Upload directory (default: OS temp). */
+    dir?: string;
+    /** Maximum size per file in bytes. */
+    maxFileSize?: number;
+    /** Reject non-HTTPS requests with 403. */
+    requireSecure?: boolean;
+    /** Maximum number of non-file fields. Default: 1000. */
+    maxFields?: number;
+    /** Maximum number of uploaded files. Default: 10. */
+    maxFiles?: number;
+    /** Maximum size of a single field value in bytes. Default: 1 MB. */
+    maxFieldSize?: number;
+    /** Whitelist of allowed MIME types for uploaded files (e.g. ['image/png', 'image/jpeg']). */
+    allowedMimeTypes?: string[];
+    /** Maximum combined size of all uploaded files in bytes. */
+    maxTotalSize?: number;
+}
+
+export interface MultipartFile {
+    originalFilename: string;
+    storedName: string;
+    path: string;
+    contentType: string;
+    size: number;
+}
+
+export function json(options?: JsonParserOptions): MiddlewareFunction;
+export function urlencoded(options?: UrlencodedParserOptions): MiddlewareFunction;
+export function text(options?: TextParserOptions): MiddlewareFunction;
+export function raw(options?: BodyParserOptions): MiddlewareFunction;
+export function multipart(options?: MultipartOptions): MiddlewareFunction;

package/types/cli.d.ts

@@ -1,2 +1,40 @@
-// Re-exports for @zero-server/cli — CLI runner types
-export { CLI, runCLI } from './orm';
+// TypeScript declarations for the bundled CLI runner (`zs` / `zh`).
+//
+// The CLI lives in `lib/cli.js` and is published both as the `zs` /
+// `zh` bin scripts and as a programmatic API on the SDK.  It dispatches
+// ORM subcommands (`migrate`, `seed`, `make:*`) to `@zero-server/orm`
+// and `webrtc:*` subcommands to `@zero-server/webrtc`, but the runner
+// itself is scope-neutral - hence its own declaration file.
+
+/**
+ * CLI runner for the bundled `zs` command.
+ *
+ * Parses `process.argv`-style input, resolves a config file
+ * (`zero.config.js` / `.zero-server.js` / `.zero-http.js`), and
+ * dispatches to the matching subcommand handler.
+ */
+export class CLI {
+    constructor(argv?: string[]);
+
+    /** The first positional argument (subcommand name). Defaults to `"help"`. */
+    readonly command: string;
+
+    /** Remaining positional arguments after the subcommand. */
+    readonly args: string[];
+
+    /** Parsed `--flag=value` and `-f value` pairs. */
+    readonly flags: Map<string, string>;
+
+    /** Execute the parsed command.  Sets `process.exitCode` on failure. */
+    run(): Promise<void>;
+}
+
+/**
+ * One-shot helper: `new CLI(argv).run()`.
+ *
+ * @example
+ *   const { runCLI } = require('@zero-server/sdk');
+ *   await runCLI(['migrate']);
+ *   await runCLI(['make:model', 'User', '--dir=src/models']);
+ */
+export function runCLI(argv?: string[]): Promise<void>;