@procedures/client 0.0.0-stage → 0.2.0

package/src/procedures/registry.ts

@@ -0,0 +1,473 @@
+/**
+ * Procedure Registry
+ *
+ * Central registry for procedure definitions.
+ * Supports auto-discovery via module self-registration pattern.
+ */
+
+import type {
+  AnyProcedure,
+  ProcedurePath,
+  RegistryEventType,
+  RegistryListener,
+  ProcedureModule,
+  RegistrationOptions,
+} from "./types.js";
+import { pathToKey } from "./types.js";
+import { validateCalls } from "./policy.js";
+
+// =============================================================================
+// Registry Errors
+// =============================================================================
+
+/**
+ * Error thrown when procedure registration fails.
+ */
+export class RegistryError extends Error {
+  override readonly name = "RegistryError";
+  readonly path: ProcedurePath;
+
+  constructor(
+    message: string,
+    path: ProcedurePath,
+    cause?: Error
+  ) {
+    super(message, { cause });
+    this.path = path;
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, RegistryError);
+    }
+  }
+}
+
+// =============================================================================
+// Path Segments
+// =============================================================================
+
+/** Segments that name properties of every object. A path must not use them. */
+const RESERVED_SEGMENTS: ReadonlySet<string> = new Set(["__proto__", "constructor", "prototype"]);
+
+/**
+ * This function checks a procedure path: at least one segment, each a non-empty string, and
+ * none of `__proto__`, `constructor` or `prototype`. A reserved segment reaches
+ * `Object.prototype` in a tree walk (deep dive CORE-6). A segment can contain a dot
+ * (`["fs", "read.json"]`), but the registry rejects two different paths with the same key.
+ *
+ * @throws RegistryError when the path is not valid
+ */
+export function assertValidPath(path: ProcedurePath): void {
+  if (!Array.isArray(path) || path.length === 0) {
+    throw new RegistryError("A procedure path must have at least one segment", path ?? []);
+  }
+  for (const segment of path) {
+    if (typeof segment !== "string" || segment === "") {
+      throw new RegistryError(`A path segment must be a non-empty string: ${JSON.stringify(path)}`, path);
+    }
+    if (RESERVED_SEGMENTS.has(segment)) {
+      throw new RegistryError(`A path segment must not be ${JSON.stringify(segment)}: ${JSON.stringify(path)}`, path);
+    }
+  }
+}
+
+function samePath(a: ProcedurePath, b: ProcedurePath): boolean {
+  return a.length === b.length && a.every((segment, index) => segment === b[index]);
+}
+
+// =============================================================================
+// Procedure Registry
+// =============================================================================
+
+/**
+ * Central registry for procedure definitions.
+ *
+ * Features:
+ * - Path-based procedure storage and lookup
+ * - Event emission for registration/unregistration
+ * - Module bulk registration with path prefixing
+ * - Tree traversal for namespace queries
+ *
+ * @example
+ * ```typescript
+ * const registry = new ProcedureRegistry();
+ *
+ * // Register a procedure
+ * registry.register(getUserProcedure);
+ *
+ * // Lookup by path
+ * const proc = registry.get(['users', 'get']);
+ *
+ * // Listen for registrations
+ * registry.on('register', (proc) => console.log('Registered:', proc.path));
+ * ```
+ */
+export class ProcedureRegistry {
+  /** Procedures stored by path key */
+  private readonly procedures = new Map<string, AnyProcedure>();
+
+  /** Event listeners */
+  private readonly listeners: RegistryListener[] = [];
+
+  /** Registered module names for debugging */
+  private readonly registeredModules = new Set<string>();
+
+  // ---------------------------------------------------------------------------
+  // Registration
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Register a procedure.
+   *
+   * @param procedure - Procedure to register
+   * @param options - Registration options
+   * @throws RegistryError if path already exists and override is false
+   */
+  register(procedure: AnyProcedure, options?: RegistrationOptions): void {
+    const path = options?.pathPrefix
+      ? [...options.pathPrefix, ...procedure.path]
+      : procedure.path;
+
+    assertValidPath(path);
+    const key = pathToKey(path);
+    // A list of nested calls that cannot be checked is an error now, not at the first call
+    try {
+      validateCalls((procedure.metadata as { calls?: unknown } | undefined)?.calls, path);
+    } catch (error) {
+      throw new RegistryError((error as Error).message, path);
+    }
+
+    const replaced = this.procedures.get(key);
+    // The key joins the segments with dots: ["a.b", "c"] and ["a", "b.c"] have one key
+    if (replaced && !samePath(replaced.path, path)) {
+      throw new RegistryError(
+        `Procedure path ${JSON.stringify(path)} has the same key as ${JSON.stringify(replaced.path)}: ${key}`,
+        path
+      );
+    }
+    if (replaced && !options?.override) {
+      throw new RegistryError(
+        `Procedure already registered at path: ${key}`,
+        path
+      );
+    }
+
+    // Store with potentially prefixed path
+    const storedProcedure: AnyProcedure = {
+      ...procedure,
+      path,
+    };
+
+    this.procedures.set(key, storedProcedure);
+    // A listener that keeps state per path sees the old procedure go first
+    if (replaced) this.emit("unregister", replaced);
+    this.emit("register", storedProcedure);
+  }
+
+  /**
+   * Unregister a procedure by path.
+   *
+   * @param path - Procedure path to unregister
+   * @returns true if procedure was found and removed
+   */
+  unregister(path: ProcedurePath): boolean {
+    const key = pathToKey(path);
+    const procedure = this.procedures.get(key);
+
+    if (procedure) {
+      this.procedures.delete(key);
+      this.emit("unregister", procedure);
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Register all procedures from a module.
+   *
+   * @param module - Module with procedures array
+   * @param options - Registration options
+   */
+  registerModule(module: ProcedureModule, options?: RegistrationOptions): void {
+    if (module.name) {
+      this.registeredModules.add(module.name);
+    }
+
+    for (const procedure of module.procedures) {
+      this.register(procedure, options);
+    }
+  }
+
+  /**
+   * Register multiple procedures.
+   *
+   * @param procedures - Array of procedures
+   * @param options - Registration options
+   */
+  registerAll(procedures: AnyProcedure[], options?: RegistrationOptions): void {
+    for (const procedure of procedures) {
+      this.register(procedure, options);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Lookup
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get a procedure by path.
+   *
+   * @param path - Procedure path
+   * @returns Procedure or undefined if not found
+   */
+  get(path: ProcedurePath): AnyProcedure | undefined {
+    return this.procedures.get(pathToKey(path));
+  }
+
+  /**
+   * Check if a procedure exists at path.
+   *
+   * @param path - Procedure path
+   */
+  has(path: ProcedurePath): boolean {
+    return this.procedures.has(pathToKey(path));
+  }
+
+  /**
+   * Get all procedures under a namespace prefix.
+   *
+   * @param prefix - Path prefix to filter by
+   * @returns Array of procedures under the prefix
+   *
+   * @example
+   * ```typescript
+   * // Get all collection procedures
+   * const collectionProcs = registry.getByPrefix(['collections']);
+   * ```
+   */
+  getByPrefix(prefix: ProcedurePath): AnyProcedure[] {
+    const prefixKey = pathToKey(prefix);
+    const results: AnyProcedure[] = [];
+
+    for (const [key, procedure] of this.procedures) {
+      if (key === prefixKey || key.startsWith(prefixKey + ".")) {
+        results.push(procedure);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Get all registered procedures.
+   */
+  getAll(): AnyProcedure[] {
+    return Array.from(this.procedures.values());
+  }
+
+  /**
+   * Get count of registered procedures.
+   */
+  get size(): number {
+    return this.procedures.size;
+  }
+
+  /**
+   * Get all registered module names.
+   */
+  getModules(): string[] {
+    return Array.from(this.registeredModules);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Tree Operations
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get the namespace tree structure.
+   * Useful for introspection and documentation generation.
+   *
+   * @returns Nested object representing the procedure tree
+   *
+   * @example
+   * ```typescript
+   * const tree = registry.getTree();
+   * // {
+   * //   collections: {
+   * //     users: { get: procedure, set: procedure },
+   * //     orders: { list: procedure }
+   * //   },
+   * //   weather: { forecast: procedure }
+   * // }
+   * ```
+   */
+  getTree(): Record<string, unknown> {
+    // Null-prototype containers and own-property checks: a segment such as "toString" is a
+    // name, not a property of Object.prototype (deep dive CORE-6)
+    const tree: Record<string, unknown> = Object.create(null);
+
+    for (const procedure of this.procedures.values()) {
+      let current = tree;
+
+      for (let i = 0; i < procedure.path.length; i++) {
+        const segment = procedure.path[i]!;
+        const isLast = i === procedure.path.length - 1;
+
+        if (isLast) {
+          current[segment] = procedure;
+        } else {
+          if (!Object.hasOwn(current, segment)) {
+            current[segment] = Object.create(null);
+          }
+          current = current[segment] as Record<string, unknown>;
+        }
+      }
+    }
+
+    return tree;
+  }
+
+  /**
+   * Get all unique namespace prefixes at a given depth.
+   *
+   * @param depth - Depth to query (0 = root namespaces)
+   * @returns Array of unique segments at that depth
+   *
+   * @example
+   * ```typescript
+   * registry.getNamespacesAtDepth(0); // ['collections', 'weather', 'auth']
+   * registry.getNamespacesAtDepth(1); // ['users', 'orders', 'forecast', ...]
+   * ```
+   */
+  getNamespacesAtDepth(depth: number): string[] {
+    const namespaces = new Set<string>();
+
+    for (const procedure of this.procedures.values()) {
+      if (procedure.path.length > depth) {
+        namespaces.add(procedure.path[depth]!);
+      }
+    }
+
+    return Array.from(namespaces);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Events
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Add event listener for registry events.
+   *
+   * @param event - Event type
+   * @param listener - Callback function
+   */
+  on(event: RegistryEventType, listener: (procedure: AnyProcedure) => void): void {
+    this.listeners.push({ event, listener });
+  }
+
+  /**
+   * Remove event listener.
+   *
+   * @param event - Event type
+   * @param listener - Callback function to remove
+   */
+  off(event: RegistryEventType, listener: (procedure: AnyProcedure) => void): void {
+    const index = this.listeners.findIndex(
+      (l) => l.event === event && l.listener === listener
+    );
+    if (index !== -1) {
+      this.listeners.splice(index, 1);
+    }
+  }
+
+  /**
+   * Emit an event to all listeners.
+   */
+  private emit(event: RegistryEventType, procedure: AnyProcedure): void {
+    for (const { event: listenerEvent, listener } of this.listeners) {
+      if (listenerEvent === event) {
+        try {
+          listener(procedure);
+        } catch (error) {
+          console.error(`Registry listener error for ${event}:`, error);
+        }
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Utilities
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Clear all registered procedures.
+   * Primarily useful for testing.
+   */
+  clear(): void {
+    const procedures = Array.from(this.procedures.values());
+
+    for (const procedure of procedures) {
+      this.procedures.delete(pathToKey(procedure.path));
+      this.emit("unregister", procedure);
+    }
+
+    this.registeredModules.clear();
+  }
+
+  /**
+   * Create a snapshot of current registrations.
+   * Useful for debugging and testing.
+   */
+  snapshot(): { paths: string[]; modules: string[] } {
+    return {
+      paths: Array.from(this.procedures.keys()),
+      modules: Array.from(this.registeredModules),
+    };
+  }
+}
+
+// =============================================================================
+// Global Registry Singleton
+// =============================================================================
+
+/**
+ * Symbol key for storing registry on globalThis.
+ * This ensures there's only ONE registry across all module loads,
+ * regardless of ESM/CJS interop issues or multiple import paths.
+ */
+const REGISTRY_KEY = Symbol.for("@procedures/client/PROCEDURE_REGISTRY");
+
+/**
+ * Get or create the global registry singleton.
+ * Uses Symbol.for to ensure the same symbol is used across all contexts.
+ */
+function getGlobalRegistry(): ProcedureRegistry {
+  const g = globalThis as Record<symbol, ProcedureRegistry | undefined>;
+  if (!g[REGISTRY_KEY]) {
+    g[REGISTRY_KEY] = new ProcedureRegistry();
+  }
+  return g[REGISTRY_KEY];
+}
+
+/**
+ * Global procedure registry singleton.
+ *
+ * Used for module self-registration pattern where modules
+ * register their procedures at import time.
+ *
+ * Note: Uses globalThis with a Symbol key to ensure there's truly
+ * only one registry across ESM/CJS boundaries and dynamic imports.
+ *
+ * @example
+ * ```typescript
+ * // In a module's register.ts (side-effect import)
+ * import { PROCEDURE_REGISTRY } from 'client/procedures';
+ * import { myProcedures } from './procedures';
+ *
+ * PROCEDURE_REGISTRY.registerAll(myProcedures);
+ *
+ * // Consumer just imports the side-effect
+ * import 'my-module/register';
+ * ```
+ */
+export const PROCEDURE_REGISTRY: ProcedureRegistry = getGlobalRegistry();

package/src/procedures/schema.ts

@@ -0,0 +1,225 @@
+/**
+ * The schemas of procedures: Standard Schema v1, validation and JSON Schema.
+ *
+ * A procedure's input and output schema is a Standard Schema (https://standardschema.dev):
+ * zod 4, valibot, arktype and other libraries give one. An older schema with only `parse` and
+ * `safeParse` (`ZodLike`) also works. Every part of the ecosystem validates and describes a
+ * schema through the two functions of this module:
+ *
+ * - `validateSchema()` validates a value (sync when the schema is sync, so a handler can start
+ *   before the first `await`).
+ * - `jsonSchemaOf()` gives the JSON Schema of the input or the output, for the MCP tools, the
+ *   help and the flags of `mark`, its manifest and the site's catalog.
+ *
+ * Before, each tool read the private fields of zod 3 (`_def`), the MCP server converted
+ * schemas with a zod 3 library, and most procedures had a schema that validated nothing.
+ */
+
+import { toJSONSchema } from "zod";
+import type { ZodLike } from "../client/validation/types.js";
+
+// =============================================================================
+// Standard Schema v1 (the interface of the specification, copied as it advises)
+// =============================================================================
+
+/** A schema of the Standard Schema specification, version 1. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The properties of the specification. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export declare namespace StandardSchemaV1 {
+  /** The properties of a Standard Schema. */
+  export interface Props<Input = unknown, Output = Input> {
+    /** The version number of the specification. */
+    readonly version: 1;
+    /** The name of the library that made the schema. */
+    readonly vendor: string;
+    /** The function that validates a value. */
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    /** The input and output types of the schema (types only). */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+
+  /** The result of a validation. */
+  export type Result<Output> = SuccessResult<Output> | FailureResult;
+
+  /** A valid value. */
+  export interface SuccessResult<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+  }
+
+  /** An invalid value. */
+  export interface FailureResult {
+    readonly issues: ReadonlyArray<Issue>;
+  }
+
+  /** One problem of an invalid value. */
+  export interface Issue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+
+  /** A part of the path of an issue. */
+  export interface PathSegment {
+    readonly key: PropertyKey;
+  }
+
+  /** The input and output types of a schema. */
+  export interface Types<Input = unknown, Output = Input> {
+    readonly input: Input;
+    readonly output: Output;
+  }
+
+  /** The input type of a Standard Schema. */
+  export type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+
+  /** The output type of a Standard Schema. */
+  export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+
+/**
+ * The JSON Schema converter of a schema (the "Standard JSON Schema" property that zod 4 gives in
+ * `~standard.jsonSchema`).
+ */
+export interface StandardJSONSchemaConverter {
+  input(options: { target: JsonSchemaTarget }): Record<string, unknown>;
+  output(options: { target: JsonSchemaTarget }): Record<string, unknown>;
+}
+
+/** The JSON Schema dialects that a converter can give. */
+export type JsonSchemaTarget = "draft-2020-12" | "draft-07" | "openapi-3.0";
+
+// =============================================================================
+// The schema of a procedure
+// =============================================================================
+
+/**
+ * The input or output schema of a procedure: a Standard Schema, or an older schema with
+ * `parse`/`safeParse` (`ZodLike`).
+ */
+export type ProcedureSchema<T = unknown> = StandardSchemaV1<unknown, T> | ZodLike<T>;
+
+/** The type that a schema gives. */
+export type InferSchema<S> =
+  S extends StandardSchemaV1<unknown, infer T> ? T : S extends ZodLike<infer U> ? U : unknown;
+
+/** True for a value that has the properties of a Standard Schema v1. */
+export function isStandardSchema(value: unknown): value is StandardSchemaV1 {
+  if (value === null || (typeof value !== "object" && typeof value !== "function")) return false;
+  const props = (value as { "~standard"?: { version?: unknown; validate?: unknown } })["~standard"];
+  return !!props && props.version === 1 && typeof props.validate === "function";
+}
+
+// =============================================================================
+// Validation
+// =============================================================================
+
+/** The result of `validateSchema()`. */
+export type SchemaResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly message: string; readonly issues: ReadonlyArray<StandardSchemaV1.Issue> };
+
+/** The text of an issue path: `filter.status` or `items[2]`. */
+function pathText(path: StandardSchemaV1.Issue["path"]): string {
+  let text = "";
+  for (const part of path ?? []) {
+    const key = typeof part === "object" && part !== null ? (part as StandardSchemaV1.PathSegment).key : part;
+    text += typeof key === "number" ? `[${key}]` : text === "" ? String(key) : `.${String(key)}`;
+  }
+  return text;
+}
+
+/** One line for each issue: `filter: Expected object, received string`. */
+export function describeIssues(issues: ReadonlyArray<StandardSchemaV1.Issue>): string {
+  return issues.map((issue) => (issue.path?.length ? `${pathText(issue.path)}: ${issue.message}` : issue.message)).join("; ");
+}
+
+function fromStandard<T>(result: StandardSchemaV1.Result<T>): SchemaResult<T> {
+  if (result.issues) {
+    return { ok: false, message: describeIssues(result.issues) || "Validation failed", issues: result.issues };
+  }
+  return { ok: true, value: (result as StandardSchemaV1.SuccessResult<T>).value };
+}
+
+/**
+ * This function validates a value against a schema. It returns a result, not a Promise, when
+ * the schema validates synchronously, so a caller can start the handler before an `await`.
+ */
+export function validateSchema<T>(schema: ProcedureSchema<T>, value: unknown): SchemaResult<T> | Promise<SchemaResult<T>> {
+  if (isStandardSchema(schema)) {
+    const result = (schema as StandardSchemaV1<unknown, T>)["~standard"].validate(value);
+    return result instanceof Promise ? result.then(fromStandard) : fromStandard(result);
+  }
+  const legacy = schema as ZodLike<T>;
+  const parsed = legacy.safeParse(value);
+  if (parsed.success) return { ok: true, value: parsed.data };
+  const error = parsed.error as { message?: string; issues?: StandardSchemaV1.Issue[]; errors?: StandardSchemaV1.Issue[] };
+  const issues = error.issues ?? error.errors ?? [{ message: error.message ?? "Validation failed" }];
+  return { ok: false, message: error.message ?? describeIssues(issues), issues };
+}
+
+/** This function validates a value and waits for an asynchronous schema. */
+export async function validateSchemaAsync<T>(schema: ProcedureSchema<T>, value: unknown): Promise<SchemaResult<T>> {
+  return validateSchema(schema, value);
+}
+
+// =============================================================================
+// JSON Schema
+// =============================================================================
+
+/** A JSON Schema object. */
+export type JsonSchema = Record<string, unknown>;
+
+/**
+ * A schema that describes itself: a pass-through schema can give a JSON Schema this way (for
+ * example `{}`, any value). A Standard Schema with a converter does not need it.
+ */
+export interface JsonSchemaSource {
+  readonly "~jsonSchema"?: JsonSchema | undefined;
+}
+
+/**
+ * The JSON Schema of the input (`io: "input"`, the default) or the output of a schema, or
+ * `undefined` when the schema cannot describe itself (a custom schema with only `parse`).
+ *
+ * The default dialect is draft-07, which every MCP client reads. A zod type that JSON cannot
+ * show (a date, a transform) becomes `{}`, so a description never fails.
+ */
+export function jsonSchemaOf(
+  schema: ProcedureSchema | undefined,
+  options: { io?: "input" | "output"; target?: JsonSchemaTarget } = {}
+): JsonSchema | undefined {
+  if (!schema) return undefined;
+  const io = options.io ?? "input";
+  const target = options.target ?? "draft-07";
+  const own = (schema as JsonSchemaSource)["~jsonSchema"];
+  if (own) return own;
+  // A zod 4 schema: z.toJSONSchema can replace the types that JSON cannot show
+  if ((schema as { _zod?: unknown })._zod !== undefined) {
+    try {
+      return withoutDialect(toJSONSchema(schema as never, { io, target, unrepresentable: "any" }) as JsonSchema);
+    } catch {
+      return undefined;
+    }
+  }
+  // Another library: its Standard JSON Schema converter
+  const converter = (schema as { "~standard"?: { jsonSchema?: StandardJSONSchemaConverter } })["~standard"]?.jsonSchema;
+  if (converter && typeof converter[io] === "function") {
+    try {
+      return withoutDialect(converter[io]({ target }));
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/** The `$schema` key names the dialect: a tool list and a manifest do not need it on each schema. */
+function withoutDialect(schema: JsonSchema): JsonSchema {
+  if (!("$schema" in schema)) return schema;
+  const { $schema: _dialect, ...rest } = schema;
+  return rest;
+}