@procedures/client 0.0.0-stage → 0.1.0

package/src/procedures/module.ts

@@ -0,0 +1,107 @@
+/**
+ * Procedure modules and explicit registries (architecture review, roadmap 3.1).
+ *
+ * Importing a package root registers its procedures in the global `PROCEDURE_REGISTRY`
+ * (DECISIONS-2026-10, "Every package root registers its procedures"). That stays. A host that
+ * wants its own registry uses the module of each package instead: the `./module` entry of a
+ * package exports its procedures as data, and importing it registers nothing.
+ *
+ * ```ts
+ * import { createRegistry, Client, LocalTransport } from "@procedures/client";
+ * import gitModule from "@procedures/git/module";
+ *
+ * const registry = createRegistry(gitModule);
+ * const client = new Client(new LocalTransport({ registry })).useRegistry(registry);
+ * ```
+ *
+ * Two registries in one process stay apart: a nested call, `procedure.define` and the expose
+ * rule of a server all use the registry of the invocation (`ctx.registry`).
+ */
+
+import { ProcedureRegistry, RegistryError } from "./registry.js";
+import { coreProcedures } from "./core/index.js";
+import { metaProcedures as definitionProcedures } from "./define-procedure.js";
+import type { AnyProcedure, ProcedureModule, RegistrationOptions } from "./types.js";
+
+/**
+ * The procedures that `@procedures/client` registers in the global registry when it is
+ * imported: the control flow (`client.chain`, `client.map` and the others) and
+ * `procedure.define`/`get`/`list`/`delete`. `createRegistry()` always registers this module, so an
+ * explicit registry has what the global registry has.
+ */
+export const clientModule: ProcedureModule = {
+  name: "@procedures/client",
+  procedures: [...coreProcedures, ...definitionProcedures],
+};
+
+/** This function gives a module: its procedures, and the modules whose procedures it calls. */
+export function defineModule(
+  name: string,
+  procedures: readonly AnyProcedure[],
+  requires: readonly ProcedureModule[] = []
+): ProcedureModule {
+  return { name, procedures: [...procedures], requires };
+}
+
+/**
+ * The modules and their required modules, each one time, with each required module before the
+ * module that requires it.
+ */
+export function moduleClosure(modules: readonly ProcedureModule[]): ProcedureModule[] {
+  const ordered: ProcedureModule[] = [];
+  const seen = new Set<ProcedureModule>();
+  const names = new Set<string>();
+  const visit = (module: ProcedureModule, trail: readonly ProcedureModule[]): void => {
+    if (seen.has(module)) return;
+    // Two copies of one package (two installs) have one name: the first one counts
+    if (module.name !== undefined && names.has(module.name)) return;
+    if (trail.includes(module)) {
+      throw new Error(`Modules require each other in a cycle: ${[...trail, module].map((m) => m.name ?? "?").join(" -> ")}`);
+    }
+    for (const required of module.requires ?? []) visit(required, [...trail, module]);
+    seen.add(module);
+    if (module.name !== undefined) names.add(module.name);
+    ordered.push(module);
+  };
+  for (const module of modules) visit(module, []);
+  return ordered;
+}
+
+/** One module, or a list of modules (a bundle can give a list). */
+export type ModuleInput = ProcedureModule | readonly ProcedureModule[];
+
+/**
+ * Register the procedures of a module and of its required modules in a registry. A procedure
+ * that the registry has already (the same handler, from a module that two modules require) is
+ * skipped. Another procedure at the same path is an error.
+ */
+export function registerModules(
+  registry: ProcedureRegistry,
+  modules: readonly ModuleInput[],
+  options?: RegistrationOptions
+): ProcedureRegistry {
+  const flat = modules.flatMap((input) => (Array.isArray(input) ? (input as readonly ProcedureModule[]) : [input as ProcedureModule]));
+  for (const module of moduleClosure(flat)) {
+    for (const procedure of module.procedures) {
+      const path = options?.pathPrefix ? [...options.pathPrefix, ...procedure.path] : procedure.path;
+      const existing = registry.get(path);
+      if (existing && !options?.override) {
+        if (existing.handler === procedure.handler) continue;
+        throw new RegistryError(
+          `Two modules give the procedure ${path.join(".")}: the second one is ${module.name ?? "a module without a name"}`,
+          path
+        );
+      }
+      registry.register(procedure, options);
+    }
+  }
+  return registry;
+}
+
+/**
+ * A new registry with the procedures of `clientModule` (what the global registry has after
+ * `import "@procedures/client"`) and of each module, with their required modules.
+ */
+export function createRegistry(...modules: ModuleInput[]): ProcedureRegistry {
+  return registerModules(new ProcedureRegistry(), [clientModule, ...modules]);
+}

package/src/procedures/policy.ts

@@ -0,0 +1,171 @@
+/**
+ * The call policy of a host: which nested calls a procedure can make (deep dive MCP-3).
+ *
+ * A host that serves procedures to an outside caller (the MCP server, a network server) gives an
+ * `expose` rule: the procedures that its callers can reach. A procedure can call other
+ * procedures through `ctx.client`. The policy decides for each nested call, with the immediate
+ * caller:
+ *
+ * - A data-driven caller (control flow, `runs-refs`, a procedure that `procedure.define` made)
+ *   runs refs that its caller chose. It can call only exposed procedures.
+ * - A code caller with `metadata.calls` can call the procedures that it declares, and the
+ *   exposed procedures.
+ * - A code caller without `calls` can call any procedure, unless the host sets `strictCalls`.
+ *   Then it can call only exposed procedures.
+ *
+ * Before, only the first rule existed. An exposed procedure of code could call any procedure, so
+ * a code procedure that turns its input into a call was a confused deputy. The declarations make
+ * the reach of each tool visible: a test of the MCP server pins it.
+ *
+ * A host without `expose` and without `strictCalls` (a library, the local CLI) checks nothing.
+ */
+
+import type { AnyProcedure, ProcedurePath } from "./types.js";
+import { pathToKey } from "./types.js";
+import { isDataDriven } from "./ref.js";
+
+/** The call policy of a host. */
+export interface CallPolicy {
+  /** The procedures that the callers of the host can reach. Without it, every procedure is exposed. */
+  expose?: ((path: ProcedurePath) => boolean) | undefined;
+  /**
+   * True: a code procedure without `metadata.calls` can call only exposed procedures. The MCP
+   * server of the dev tools sets it.
+   */
+  strictCalls?: boolean | undefined;
+}
+
+/** The reason of a refused nested call. */
+export interface CallRefusal {
+  readonly code: "NOT_EXPOSED" | "NOT_DECLARED";
+  readonly message: string;
+}
+
+/** True when a host has a policy: a nested call is examined only then. */
+export function hasCallPolicy(policy: CallPolicy): boolean {
+  return policy.expose !== undefined || policy.strictCalls === true;
+}
+
+/**
+ * True when one entry of `calls` allows a procedure key: the same key, or `"ns.*"` for a key
+ * that starts with `"ns."` (at any depth: `"fs.*"` allows `fs.read.json`).
+ */
+export function callMatches(entry: string, key: string): boolean {
+  if (entry.endsWith(".*")) {
+    return key.startsWith(entry.slice(0, -1));
+  }
+  return entry === key;
+}
+
+/**
+ * This function checks the `calls` of a procedure's metadata and returns it, or undefined when
+ * there is none. It throws for an invalid list. `"*"` alone is refused: a procedure whose
+ * callees come from its input is data-driven and must have the `runs-refs` tag.
+ */
+export function validateCalls(calls: unknown, path: ProcedurePath): readonly string[] | undefined {
+  if (calls === undefined) return undefined;
+  const where = pathToKey(path);
+  if (!Array.isArray(calls)) {
+    throw new TypeError(`metadata.calls of ${where} must be a list of procedure keys`);
+  }
+  for (const entry of calls) {
+    if (typeof entry !== "string" || entry.length === 0) {
+      throw new TypeError(`metadata.calls of ${where} has an entry that is not a procedure key: ${JSON.stringify(entry)}`);
+    }
+    if (entry === "*") {
+      throw new TypeError(
+        `metadata.calls of ${where} is "*". A procedure whose callees come from its input is data-driven: ` +
+          `give it the "runs-refs" tag instead.`,
+      );
+    }
+    const body = entry.endsWith(".*") ? entry.slice(0, -2) : entry;
+    if (body.length === 0 || body.includes("*") || body.split(".").some((segment) => segment.length === 0)) {
+      throw new TypeError(`metadata.calls of ${where} has an invalid entry: "${entry}". Use "ns.name" or "ns.*".`);
+    }
+  }
+  return calls as readonly string[];
+}
+
+/** The `calls` of a procedure, or undefined when it declares none. */
+export function declaredCalls(procedure: Pick<AnyProcedure, "path" | "metadata">): readonly string[] | undefined {
+  return validateCalls((procedure.metadata as { calls?: unknown } | undefined)?.calls, procedure.path);
+}
+
+/** One edge of the reach of the exposed procedures: a declared call to a procedure that is not exposed. */
+export interface HiddenCall {
+  readonly from: string;
+  readonly to: string;
+}
+
+/**
+ * The procedures that are not exposed, but that the exposed procedures can reach through their
+ * `metadata.calls`, also through more than one step. A data-driven procedure reaches only
+ * exposed procedures, and under `strictCalls` a procedure without `calls` does too, so neither
+ * adds an edge. The edges are sorted. A test of the MCP server pins them.
+ */
+export function hiddenReach(
+  procedures: readonly AnyProcedure[],
+  expose: (path: ProcedurePath) => boolean,
+): HiddenCall[] {
+  const byKey = new Map(procedures.filter((procedure) => procedure.handler).map((procedure) => [pathToKey(procedure.path), procedure]));
+  const edges = new Map<string, HiddenCall>();
+  const visited = new Set<string>();
+  const visit = (procedure: AnyProcedure): void => {
+    const from = pathToKey(procedure.path);
+    if (visited.has(from)) return;
+    visited.add(from);
+    if (isDataDriven(procedure)) return;
+    for (const entry of declaredCalls(procedure) ?? []) {
+      for (const [key, callee] of byKey) {
+        if (!callMatches(entry, key) || expose(callee.path)) continue;
+        edges.set(`${from} -> ${key}`, { from, to: key });
+        visit(callee);
+      }
+    }
+  };
+  for (const procedure of byKey.values()) {
+    if (expose(procedure.path)) visit(procedure);
+  }
+  return [...edges.keys()].sort().map((key) => edges.get(key)!);
+}
+
+/**
+ * The refusal of a nested call from `caller` to `path` under `policy`, or undefined when the
+ * call is allowed.
+ */
+export function nestedCallRefusal(caller: AnyProcedure, path: ProcedurePath, policy: CallPolicy): CallRefusal | undefined {
+  if (!hasCallPolicy(policy)) return undefined;
+  const exposed = policy.expose ? policy.expose(path) : true;
+  const key = pathToKey(path);
+  const from = pathToKey(caller.path);
+
+  if (isDataDriven(caller)) {
+    return exposed
+      ? undefined
+      : {
+          code: "NOT_EXPOSED",
+          message:
+            `Procedure not exposed: ${key}. ${from} runs procedure refs from its input, so it can call only ` +
+            `the procedures that this server exposes.`,
+        };
+  }
+
+  const calls = declaredCalls(caller);
+  if (calls !== undefined) {
+    if (exposed || calls.some((entry) => callMatches(entry, key))) return undefined;
+    return {
+      code: "NOT_DECLARED",
+      message: `Procedure not declared: ${from} calls ${key}, but its metadata.calls does not name it.`,
+    };
+  }
+
+  if (policy.strictCalls && !exposed) {
+    return {
+      code: "NOT_EXPOSED",
+      message:
+        `Procedure not exposed: ${key}. ${from} declares no metadata.calls, and this server lets such a ` +
+        `procedure call only the procedures that it exposes.`,
+    };
+  }
+  return undefined;
+}