@procedures/peer 0.0.0-stage → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Type definitions for client-server procedures
+ */
+export type TransportType = "http" | "websocket" | "local";
+export interface HttpTransportConfig {
+    type: "http";
+    port?: number | undefined;
+    host?: string | undefined;
+    basePath?: string | undefined;
+    /** Send CORS headers. The default is false: only `corsOrigins` (or loopback pages) are served to browsers. */
+    cors?: boolean | undefined;
+    /** Browser origins that may call the peer, besides loopback origins */
+    corsOrigins?: string[] | undefined;
+    /** URL strategy: "rest" (default) or "rpc" for /rpc/service/operation format */
+    urlStrategy?: "rest" | "rpc" | undefined;
+    /** A secret that every request must send as `Authorization: Bearer <token>` */
+    token?: string | undefined;
+}
+export interface WebSocketTransportConfig {
+    type: "websocket";
+    port?: number | undefined;
+    host?: string | undefined;
+    path?: string | undefined;
+    /** Browser origins that may connect, besides loopback origins */
+    origins?: string[] | undefined;
+    /** A secret that every connection must send as `?token=<token>` (or a bearer header) */
+    token?: string | undefined;
+}
+export interface LocalTransportConfig {
+    type: "local";
+}
+export type TransportConfig = HttpTransportConfig | WebSocketTransportConfig | LocalTransportConfig;
+export interface ServerCreateInput {
+    /** Transports to enable */
+    transports?: TransportConfig[] | undefined;
+    /** Auto-register all procedures from registry */
+    autoRegister?: boolean | undefined;
+    /** A secret that every request must carry (each transport that has no token of its own gets this one) */
+    token?: string | undefined;
+    /** The procedures to serve: exact keys (`git.status`) or prefixes (`git.*`). Default: every procedure */
+    expose?: string[] | undefined;
+}
+export interface ServerCreateOutput {
+    /** Server ID for reference */
+    serverId: string;
+    /** Active transport endpoints */
+    endpoints: Array<{
+        type: TransportType;
+        address: string;
+    }>;
+    /** Number of registered procedures */
+    procedureCount: number;
+}
+export interface ServerConnectInput {
+    /** Remote server address */
+    address: string;
+    /** Transport type to use */
+    transport?: TransportType | undefined;
+    /** Connection timeout in ms */
+    timeout?: number | undefined;
+}
+export interface ProcedureInfo {
+    /** Procedure path */
+    path: string[];
+    /** Description from metadata */
+    description?: string | undefined;
+    /** Input schema as JSON schema */
+    inputSchema?: Record<string, unknown> | undefined;
+    /** Output schema as JSON schema */
+    outputSchema?: Record<string, unknown> | undefined;
+}
+export interface ServerConnectOutput {
+    /** Connection ID */
+    connectionId: string;
+    /** Remote peer ID */
+    remotePeerId: string;
+    /** Procedures available on remote */
+    remoteProcedures: ProcedureInfo[];
+}
+export interface ServerDisconnectInput {
+    /** Connection ID to disconnect */
+    connectionId: string;
+}
+export interface ServerDisconnectOutput {
+    /** Whether disconnect succeeded */
+    success: boolean;
+}
+export type ManifestFormat = "json" | "typescript";
+export interface ManifestGenerateInput {
+    /** Output formats to generate */
+    formats?: ManifestFormat[] | undefined;
+    /** Namespace filter (only include procedures under this path) */
+    namespace?: string[] | undefined;
+    /** Output directory for files */
+    outputDir?: string | undefined;
+}
+export interface ManifestGenerateOutput {
+    /** Generated JSON manifest */
+    json?: {
+        procedures: ProcedureInfo[];
+        generatedAt: string;
+        version: string;
+    } | undefined;
+    /** Generated TypeScript declaration */
+    typescript?: string | undefined;
+    /** Files written if outputDir provided */
+    filesWritten?: string[] | undefined;
+}
+export interface PeerConnection {
+    /** Unique connection ID */
+    id: string;
+    /** Remote peer ID */
+    remotePeerId: string;
+    /** Transport type used */
+    transport: TransportType;
+    /** Connection state */
+    state: "connecting" | "connected" | "disconnected" | "error";
+    /** Remote procedures */
+    remoteProcedures: ProcedureInfo[];
+    /** When connection was established */
+    connectedAt?: Date;
+}
+export interface ProcedureAnnounceMessage {
+    type: "procedure-announce";
+    peerId: string;
+    procedures: ProcedureInfo[];
+}
+export interface ProcedureUpdateMessage {
+    type: "procedure-update";
+    peerId: string;
+    added?: ProcedureInfo[];
+    removed?: string[];
+}
+export interface ServerStartInput {
+    /** Port to listen on */
+    port?: number | undefined;
+    /** Host to bind to */
+    host?: string | undefined;
+    /** Transport type */
+    transport?: "http" | "websocket" | "both" | undefined;
+}
+export interface ServerStartOutput {
+    /** Whether start succeeded */
+    success: boolean;
+    /** Process ID of server */
+    pid?: number | undefined;
+    /** Port server is running on */
+    port?: number | undefined;
+    /** Endpoint URL */
+    endpoint?: string | undefined;
+    /** Log file path */
+    logFile?: string | undefined;
+    /** Status message */
+    message: string;
+}
+export interface ServerStopInput {
+    /** Port of server to stop (stops all if omitted) */
+    port?: number | undefined;
+    /** Force kill with SIGKILL instead of SIGTERM */
+    force?: boolean | undefined;
+}
+export interface ServerStopOutput {
+    /** Whether stop succeeded */
+    success: boolean;
+    /** Status message */
+    message: string;
+}
+export interface ServerStatusInput {
+    /** Port to check (shows all if omitted) */
+    port?: number | undefined;
+}
+export interface ServerStatusOutput {
+    /** Whether server is running */
+    running: boolean;
+    /** Process ID */
+    pid?: number | undefined;
+    /** Port */
+    port?: number | undefined;
+    /** Endpoint URL */
+    endpoint?: string | undefined;
+    /** Transport type */
+    transport?: string | undefined;
+    /** When server started (ISO string) */
+    startedAt?: string | undefined;
+    /** Human-readable uptime */
+    uptime?: string | undefined;
+    /** Log file path */
+    logFile?: string | undefined;
+    /** Status message */
+    message: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,8GAA8G;IAC9G,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACnC,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;IACzC,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC/B,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG,wBAAwB,GAAG,oBAAoB,CAAC;AAMpG,MAAM,WAAW,iBAAiB;IAChC,2BAA2B;IAC3B,UAAU,CAAC,EAAE,eAAe,EAAE,GAAG,SAAS,CAAC;IAC3C,iDAAiD;IACjD,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACnC,yGAAyG;IACzG,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,yGAAyG;IACzG,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,SAAS,EAAE,KAAK,CAAC;QACf,IAAI,EAAE,aAAa,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;CACxB;AAMD,MAAM,WAAW,kBAAkB;IACjC,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,SAAS,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACtC,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,qBAAqB;IACrB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAClD,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CACpD;AAED,MAAM,WAAW,mBAAmB;IAClC,oBAAoB;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,gBAAgB,EAAE,aAAa,EAAE,CAAC;CACnC;AAMD,MAAM,WAAW,qBAAqB;IACpC,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,YAAY,CAAC;AAEnD,MAAM,WAAW,qBAAqB;IACpC,iCAAiC;IACjC,OAAO,CAAC,EAAE,cAAc,EAAE,GAAG,SAAS,CAAC;IACvC,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACjC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,sBAAsB;IACrC,8BAA8B;IAC9B,IAAI,CAAC,EACD;QACE,UAAU,EAAE,aAAa,EAAE,CAAC;QAC5B,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;KACjB,GACD,SAAS,CAAC;IACd,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACrC;AAMD,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,qBAAqB;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,0BAA0B;IAC1B,SAAS,EAAE,aAAa,CAAC;IACzB,uBAAuB;IACvB,KAAK,EAAE,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,OAAO,CAAC;IAC7D,wBAAwB;IACxB,gBAAgB,EAAE,aAAa,EAAE,CAAC;IAClC,sCAAsC;IACtC,WAAW,CAAC,EAAE,IAAI,CAAC;CACpB;AAMD,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,aAAa,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAMD,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,sBAAsB;IACtB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS,CAAC;CACvD;AAED,MAAM,WAAW,iBAAiB;IAChC,8BAA8B;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,2BAA2B;IAC3B,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,mBAAmB;IACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,oBAAoB;IACpB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,iBAAiB;IACjB,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,WAAW;IACX,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,mBAAmB;IACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,oBAAoB;IACpB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Type definitions for client-server procedures
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -1,6 +1,90 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/peer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Serve procedures: HTTP and WebSocket peers with token authentication, browser checks, an expose list, server.create, status and stop, and manifests.",
+  "keywords": [
+    "server",
+    "rpc",
+    "http",
+    "websocket",
+    "peer",
+    "authentication",
+    "procedures"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/client-server"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./module": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    },
+    "./procedures": {
+      "types": "./dist/procedures/index.d.ts",
+      "import": "./dist/procedures/index.js"
+    },
+    "./lockfile": {
+      "types": "./dist/lockfile.d.ts",
+      "import": "./dist/lockfile.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/index.js",
+    "./dist/register.js"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "@types/node": "^22.0.0",
+    "@mark1russell7/cue": "^1.0.0",
+    "vitest": "^5.0.3",
+    "@types/express": "^5.0.6"
+  },
+  "client": {
+    "procedures": "./dist/register.js"
+  },
+  "dependencies": {
+    "@procedures/client": "0.1.0",
+    "zod": "^4.6.5"
+  },
+  "optionalDependencies": {
+    "express": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }

package/src/connection/index.ts

@@ -0,0 +1,219 @@
+/**
+ * Connection Module
+ *
+ * Manages outbound connections to remote peers.
+ * Uses Client + Transport for bidirectional RPC.
+ */
+
+import {
+  Client,
+  HttpTransport,
+  WebSocketTransport,
+  defaultUrlPattern,
+  postOnlyStrategy,
+  type HttpTransportOptions,
+} from "@procedures/client";
+import type {
+  TransportType,
+  PeerConnection,
+  ProcedureInfo,
+  ProcedureAnnounceMessage,
+} from "../types.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ConnectOptions {
+  /** Remote address (URL) */
+  address: string;
+  /** Transport type (auto-detected from URL if not specified) */
+  transport?: TransportType;
+  /** Connection timeout in ms */
+  timeout?: number;
+  /** Local peer ID to identify ourselves */
+  localPeerId?: string;
+}
+
+export interface Connection {
+  /** Connection ID */
+  id: string;
+  /** Remote peer info */
+  remote: PeerConnection;
+  /** Client for calling remote procedures */
+  client: Client;
+  /** Disconnect */
+  disconnect(): Promise<void>;
+}
+
+// =============================================================================
+// Connection Manager
+// =============================================================================
+
+/** Active connections */
+const connections = new Map<string, Connection>();
+
+/**
+ * Connect to a remote peer
+ */
+export async function connect(options: ConnectOptions): Promise<Connection> {
+  const connectionId = `conn-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+  // Detect transport type from URL if not specified
+  const transport = options.transport ?? detectTransport(options.address);
+
+  // Create appropriate client transport
+  const client = createClient(options.address, transport, options.timeout);
+
+  // Discover remote procedures
+  const remoteProcedures = await discoverProcedures(client, options.localPeerId);
+
+  // Create connection object
+  const connection: Connection = {
+    id: connectionId,
+    remote: {
+      id: connectionId,
+      remotePeerId: remoteProcedures.peerId,
+      transport,
+      state: "connected",
+      remoteProcedures: remoteProcedures.procedures,
+      connectedAt: new Date(),
+    },
+    client,
+    async disconnect() {
+      await client.close();
+      connections.delete(connectionId);
+    },
+  };
+
+  connections.set(connectionId, connection);
+  return connection;
+}
+
+/**
+ * Get connection by ID
+ */
+export function getConnection(connectionId: string): Connection | undefined {
+  return connections.get(connectionId);
+}
+
+/**
+ * Disconnect a connection
+ */
+export async function disconnect(connectionId: string): Promise<boolean> {
+  const connection = connections.get(connectionId);
+  if (!connection) {
+    return false;
+  }
+  await connection.disconnect();
+  return true;
+}
+
+/**
+ * Get all active connection IDs
+ */
+export function getConnectionIds(): string[] {
+  return Array.from(connections.keys());
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * Detect transport type from URL
+ */
+function detectTransport(address: string): TransportType {
+  if (address.startsWith("ws://") || address.startsWith("wss://")) {
+    return "websocket";
+  }
+  if (address.startsWith("http://") || address.startsWith("https://")) {
+    return "http";
+  }
+  if (address.startsWith("local://")) {
+    return "local";
+  }
+  // Default to HTTP
+  return "http";
+}
+
+/**
+ * Create client with appropriate transport
+ */
+function createClient(
+  address: string,
+  transport: TransportType,
+  timeout?: number
+): Client {
+  switch (transport) {
+    case "http": {
+      const httpOptions: HttpTransportOptions = {
+        baseUrl: address,
+        urlStrategy: defaultUrlPattern.format,
+        httpMethodStrategy: postOnlyStrategy,
+      };
+      if (timeout !== undefined) {
+        httpOptions.timeout = timeout;
+      }
+      return new Client({
+        transport: new HttpTransport(httpOptions),
+      });
+    }
+
+    case "websocket":
+      return new Client({
+        transport: new WebSocketTransport({
+          url: address,
+          connectionTimeout: timeout ?? 10000,
+          reconnect: {
+            enabled: true,
+            maxAttempts: 3,
+          },
+        }),
+      });
+
+    case "local":
+      throw new Error("Local transport for outbound connections not yet implemented");
+
+    default:
+      throw new Error(`Unknown transport type: ${transport}`);
+  }
+}
+
+/**
+ * Discover procedures on remote peer
+ */
+async function discoverProcedures(
+  client: Client,
+  localPeerId?: string
+): Promise<{ peerId: string; procedures: ProcedureInfo[] }> {
+  try {
+    // Build payload - only include peerId if defined
+    const payload: { peerId?: string } = {};
+    if (localPeerId !== undefined) {
+      payload.peerId = localPeerId;
+    }
+
+    // Call the discovery endpoint
+    const response = await client.call<
+      { peerId?: string },
+      ProcedureAnnounceMessage
+    >(
+      { service: "_discovery", operation: "announce" },
+      payload
+    );
+
+    return {
+      peerId: response.peerId,
+      procedures: response.procedures,
+    };
+  } catch (error) {
+    // If discovery fails, return empty procedures
+    // The connection is still valid, just no auto-discovery
+    console.warn("Procedure discovery failed:", error);
+    return {
+      peerId: "unknown",
+      procedures: [],
+    };
+  }
+}

package/src/discovery/index.ts

@@ -0,0 +1,137 @@
+/**
+ * Discovery Module
+ *
+ * Implements procedure discovery protocol for peers.
+ * Peers exchange procedure manifests on connection.
+ */
+
+import {
+  createProcedure,
+  type Procedure,
+  PROCEDURE_REGISTRY,
+} from "@procedures/client";
+import { schema } from "../schema.js";
+import type {
+  ProcedureInfo,
+  ProcedureAnnounceMessage,
+} from "../types.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface DiscoveryAnnounceInput {
+  /** Optional peer ID of the connecting peer */
+  peerId?: string;
+}
+
+// =============================================================================
+// Discovery Procedure
+// =============================================================================
+
+const discoveryAnnounceInputSchema = schema<DiscoveryAnnounceInput>();
+const discoveryAnnounceOutputSchema = schema<ProcedureAnnounceMessage>();
+
+/**
+ * Internal procedure for procedure discovery
+ * Exposed at _discovery.announce
+ */
+export const discoveryAnnounceProcedure: Procedure<
+  DiscoveryAnnounceInput,
+  ProcedureAnnounceMessage,
+  { description: string; internal: boolean }
+> = createProcedure()
+  .path(["_discovery", "announce"])
+  .input(discoveryAnnounceInputSchema)
+  .output(discoveryAnnounceOutputSchema)
+  .meta({
+    description: "Exchange procedure manifests for discovery",
+    internal: true,
+  })
+  .handler(async (_input: DiscoveryAnnounceInput) => {
+    // Get all registered procedures
+    const procedures = PROCEDURE_REGISTRY.getAll();
+
+    // Convert to ProcedureInfo format
+    const procedureInfos: ProcedureInfo[] = procedures
+      .filter((proc) => {
+        // Skip internal procedures in discovery
+        const meta = proc.metadata as { internal?: boolean } | undefined;
+        return !meta?.internal;
+      })
+      .map((proc) => {
+        const meta = proc.metadata as { description?: string } | undefined;
+        const info: ProcedureInfo = {
+          path: proc.path,
+        };
+        if (meta?.description !== undefined) {
+          info.description = meta.description;
+        }
+        // TODO: Generate JSON schema from input/output schemas
+        return info;
+      });
+
+    // Generate a peer ID based on process (could be configured)
+    const peerId = `peer-${process.pid}-${Date.now().toString(36)}`;
+
+    return {
+      type: "procedure-announce" as const,
+      peerId,
+      procedures: procedureInfos,
+    };
+  })
+  .build();
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Get procedure info for all registered procedures
+ */
+export function getProcedureInfos(): ProcedureInfo[] {
+  const procedures = PROCEDURE_REGISTRY.getAll();
+
+  return procedures
+    .filter((proc) => proc.handler !== undefined)
+    .map((proc) => {
+      const meta = proc.metadata as { description?: string } | undefined;
+      const info: ProcedureInfo = {
+        path: proc.path,
+      };
+      if (meta?.description !== undefined) {
+        info.description = meta.description;
+      }
+      return info;
+    });
+}
+
+/**
+ * Watch for procedure changes
+ */
+export function watchProcedures(
+  callback: (event: "register" | "unregister", info: ProcedureInfo) => void
+): () => void {
+  const createHandler = (eventType: "register" | "unregister") => {
+    return (proc: { path: string[]; metadata?: { description?: string } }) => {
+      const info: ProcedureInfo = {
+        path: proc.path,
+      };
+      if (proc.metadata?.description !== undefined) {
+        info.description = proc.metadata.description;
+      }
+      callback(eventType, info);
+    };
+  };
+
+  const registerHandler = createHandler("register");
+  const unregisterHandler = createHandler("unregister");
+
+  PROCEDURE_REGISTRY.on("register", registerHandler);
+  PROCEDURE_REGISTRY.on("unregister", unregisterHandler);
+
+  return () => {
+    PROCEDURE_REGISTRY.off("register", registerHandler);
+    PROCEDURE_REGISTRY.off("unregister", unregisterHandler);
+  };
+}

package/src/expose.ts

@@ -0,0 +1,17 @@
+/**
+ * The expose rule of a server, from a list of patterns.
+ *
+ * A pattern is an exact procedure key (`git.status`), a prefix with `.*` (`git.*`: every
+ * procedure under `git`, at any depth), or `*` (every procedure). A server without a list
+ * serves every procedure of its registry.
+ *
+ * The rule is `exposePatterns()` of the core host policy (roadmap 2.3); this name stays for the
+ * callers of `client-server`.
+ */
+
+import { exposePatterns, type ProcedurePath } from "@procedures/client";
+
+/** This function gives the rule of `ProcedureServer` for a list of patterns. */
+export function exposeRule(patterns: readonly string[]): (path: ProcedurePath) => boolean {
+  return exposePatterns(patterns);
+}