@classytic/arc 2.2.5 → 2.4.1

package/dist/resourceToTools-B6ZN9Ing.mjs

@@ -0,0 +1,489 @@
+import { t as BaseController } from "./BaseController-CkM5dUh_.mjs";
+import { t as pluralize } from "./pluralize-CcT6qF0a.mjs";
+import { z } from "zod";
+//#region src/integrations/mcp/createMcpServer.ts
+/**
+* Create a configured MCP server from declarative config.
+*
+* @param config - Server name, version, tools, prompts
+* @returns McpServer instance (not yet connected to a transport)
+*/
+async function createMcpServer(config, authRef) {
+	const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+	const server = new McpServer({
+		name: config.name,
+		version: config.version ?? "1.0.0"
+	}, config.instructions ? { instructions: config.instructions } : void 0);
+	if (config.tools) for (const tool of config.tools) registerTool(server, tool, authRef);
+	if (config.prompts) for (const prompt of config.prompts) registerPrompt(server, prompt);
+	return server;
+}
+/**
+* Register a ToolDefinition using `server.registerTool()`.
+*
+* The inputSchema is passed as a flat Zod shape `{ field: z.string() }` —
+* the SDK wraps it in z.object() internally. This avoids the Zod v3/v4-mini
+* version mismatch entirely.
+*/
+function registerTool(server, tool, authRef) {
+	const srv = server;
+	const config = {};
+	if (tool.title) config.title = tool.title;
+	if (tool.description) config.description = tool.description;
+	if (tool.inputSchema) config.inputSchema = tool.inputSchema;
+	if (tool.outputSchema) config.outputSchema = tool.outputSchema;
+	if (tool.annotations) config.annotations = tool.annotations;
+	srv.registerTool(tool.name, config, (input, extra) => {
+		const ctx = {
+			session: authRef?.current ?? null,
+			log: async (level, message) => {
+				try {
+					const notify = extra?.sendNotification;
+					if (notify) await notify({
+						method: "notifications/message",
+						params: {
+							level,
+							data: message
+						}
+					});
+				} catch {}
+			},
+			extra
+		};
+		return tool.handler(input, ctx);
+	});
+}
+/** Register a PromptDefinition using `server.registerPrompt()` */
+function registerPrompt(server, prompt) {
+	const srv = server;
+	const config = {};
+	if (prompt.title) config.title = prompt.title;
+	if (prompt.description) config.description = prompt.description;
+	if (prompt.argsSchema) config.argsSchema = prompt.argsSchema;
+	srv.registerPrompt(prompt.name, config, (args) => prompt.handler(args));
+}
+//#endregion
+//#region src/integrations/mcp/fieldRulesToZod.ts
+/**
+* @classytic/arc — fieldRules → Zod Shape Converter
+*
+* Converts Arc's schemaOptions.fieldRules into flat Zod shapes
+* compatible with the MCP SDK's registerTool() inputSchema format.
+*
+* Returns `Record<string, z.ZodTypeAny>` (flat shape), NOT z.object().
+* The SDK wraps it internally.
+*
+* @example
+* ```typescript
+* import { fieldRulesToZod } from '@classytic/arc/mcp';
+*
+* const shape = fieldRulesToZod(resource.schemaOptions.fieldRules, {
+*   mode: 'create',
+*   hiddenFields: resource.schemaOptions.hiddenFields,
+* });
+* // shape = { name: z.string(), price: z.number() }
+* ```
+*/
+const PAGINATION_SHAPE = {
+	page: z.number().int().min(1).optional().describe("Page number (1-based)"),
+	limit: z.number().int().min(1).max(100).optional().describe("Items per page (max 100)"),
+	sort: z.string().optional().describe("Sort field, prefix with - for descending"),
+	search: z.string().optional().describe("Full-text search query")
+};
+/**
+* Convert Arc fieldRules to a flat Zod shape.
+*
+* @returns Flat shape `Record<string, z.ZodTypeAny>` — pass directly to defineTool() or registerTool()
+*/
+function fieldRulesToZod(fieldRules, options = {}) {
+	const { mode = "create", hiddenFields = [], readonlyFields = [], extraHideFields = [] } = options;
+	if (mode === "list") return buildListShape(fieldRules, options);
+	if (!fieldRules) return {};
+	const allHidden = new Set([...hiddenFields, ...extraHideFields]);
+	const allReadonly = new Set(readonlyFields);
+	const shape = {};
+	for (const [name, rule] of Object.entries(fieldRules)) {
+		if (rule.systemManaged || rule.hidden || allHidden.has(name)) continue;
+		if (allReadonly.has(name)) continue;
+		if (mode === "update" && rule.immutable) continue;
+		const field = buildFieldSchema(rule);
+		if (mode === "update") shape[name] = field.optional();
+		else shape[name] = rule.required === true && !rule.optional ? field : field.optional();
+	}
+	return shape;
+}
+/** Build Zod type for a single field rule */
+function buildFieldSchema(rule) {
+	if (rule.enum?.length) {
+		const schema = z.enum(rule.enum);
+		return rule.description ? schema.describe(rule.description) : schema;
+	}
+	const base = typeToZod(rule.type);
+	if (base instanceof z.ZodString) {
+		let s = base;
+		if (rule.minLength != null) s = s.min(rule.minLength);
+		if (rule.maxLength != null) s = s.max(rule.maxLength);
+		if (rule.pattern) try {
+			s = s.regex(new RegExp(rule.pattern));
+		} catch {}
+		return rule.description ? s.describe(rule.description) : s;
+	}
+	if (base instanceof z.ZodNumber) {
+		let n = base;
+		if (rule.min != null) n = n.min(rule.min);
+		if (rule.max != null) n = n.max(rule.max);
+		return rule.description ? n.describe(rule.description) : n;
+	}
+	return rule.description ? base.describe(rule.description) : base;
+}
+/** Map Arc field type string to base Zod type */
+function typeToZod(type) {
+	switch (type) {
+		case "string": return z.string();
+		case "number": return z.number();
+		case "boolean": return z.boolean();
+		case "date": return z.string().describe("ISO 8601 date string");
+		case "array": return z.array(z.any());
+		case "object": return z.record(z.string(), z.any());
+		default: return z.string();
+	}
+}
+/** Build list/query shape with filterable fields + pagination */
+function buildListShape(fieldRules, options) {
+	const { filterableFields = [], hiddenFields = [], extraHideFields = [] } = options;
+	const allHidden = new Set([...hiddenFields, ...extraHideFields]);
+	const shape = { ...PAGINATION_SHAPE };
+	if (fieldRules) for (const name of filterableFields) {
+		if (allHidden.has(name)) continue;
+		const rule = fieldRules[name];
+		if (!rule) continue;
+		shape[name] = buildFieldSchema(rule).optional();
+	}
+	return shape;
+}
+//#endregion
+//#region src/integrations/mcp/buildRequestContext.ts
+/**
+* Build an IRequestContext from MCP tool input and session auth.
+*
+* | Operation | params     | query                | body                |
+* |-----------|------------|----------------------|---------------------|
+* | list      | {}         | all input fields     | undefined           |
+* | get       | { id }     | {}                   | undefined           |
+* | create    | {}         | {}                   | all input fields    |
+* | update    | { id }     | {}                   | input minus id      |
+* | delete    | { id }     | {}                   | undefined           |
+*/
+function buildRequestContext(input, auth, operation) {
+	const scope = buildScope(auth);
+	const base = {
+		user: auth ? {
+			id: auth.userId,
+			_id: auth.userId
+		} : null,
+		headers: {},
+		context: {},
+		metadata: {
+			_scope: scope,
+			_policyFilters: {}
+		}
+	};
+	switch (operation) {
+		case "list": return {
+			...base,
+			params: {},
+			query: { ...input },
+			body: void 0
+		};
+		case "get": return {
+			...base,
+			params: { id: String(input.id ?? "") },
+			query: {},
+			body: void 0
+		};
+		case "create": return {
+			...base,
+			params: {},
+			query: {},
+			body: { ...input }
+		};
+		case "update": {
+			const { id: _id, ...body } = input;
+			return {
+				...base,
+				params: { id: String(_id ?? "") },
+				query: {},
+				body
+			};
+		}
+		case "delete": return {
+			...base,
+			params: { id: String(input.id ?? "") },
+			query: {},
+			body: void 0
+		};
+	}
+}
+function buildScope(auth) {
+	if (!auth) return { kind: "public" };
+	if (auth.organizationId) return {
+		kind: "member",
+		userId: auth.userId,
+		userRoles: [],
+		organizationId: auth.organizationId,
+		orgRoles: []
+	};
+	return {
+		kind: "authenticated",
+		userId: auth.userId,
+		userRoles: []
+	};
+}
+//#endregion
+//#region src/integrations/mcp/resourceToTools.ts
+/**
+* @classytic/arc — Resource → MCP Tools Generator
+*
+* Converts a ResourceDefinition into an array of ToolDefinitions.
+* Core auto-generation logic that powers Level 1 (mcpPlugin).
+*
+* All tool handlers call BaseController methods — same pipeline as REST.
+*/
+const ALL_CRUD_OPS = [
+	"list",
+	"get",
+	"create",
+	"update",
+	"delete"
+];
+const ANNOTATIONS = {
+	list: { readOnlyHint: true },
+	get: { readOnlyHint: true },
+	create: { destructiveHint: false },
+	update: {
+		destructiveHint: true,
+		idempotentHint: true
+	},
+	delete: {
+		destructiveHint: true,
+		idempotentHint: true
+	}
+};
+/**
+* Convert a ResourceDefinition into MCP ToolDefinitions.
+*
+* MCP tools call BaseController directly — they bypass HTTP routes entirely.
+* Therefore `disableDefaultRoutes` does NOT affect MCP tool generation;
+* only `disabledRoutes` (the per-operation array) controls which ops are skipped.
+*
+* If the resource has an adapter but no controller (e.g. `disableDefaultRoutes: true`),
+* a lightweight BaseController is auto-created from the adapter for MCP use.
+*
+* @param resource - Arc resource definition
+* @param config - Optional overrides (operations, descriptions, hideFields, prefix, names)
+*/
+function resourceToTools(resource, config = {}) {
+	const controller = resource.controller ?? (resource.adapter ? createMcpController(resource) : void 0);
+	if (!controller) return [];
+	const fieldRules = resource.schemaOptions?.fieldRules;
+	const hiddenFields = resource.schemaOptions?.hiddenFields;
+	const readonlyFields = resource.schemaOptions?.readonlyFields;
+	const filterableFields = resource.schemaOptions?.filterableFields ?? resource.queryParser?.allowedFilterFields;
+	const sortableFields = resource.queryParser?.allowedSortFields;
+	const allowedOperators = resource.queryParser?.allowedOperators;
+	const hasSoftDelete = resource._appliedPresets?.includes("softDelete") ?? false;
+	let ops = ALL_CRUD_OPS.filter((op) => {
+		if (resource.disabledRoutes?.includes(op)) return false;
+		return true;
+	});
+	if (config.operations) ops = ops.filter((op) => config.operations?.includes(op));
+	const tools = [];
+	const prefix = config.toolNamePrefix;
+	for (const op of ops) {
+		const name = config.names?.[op] ?? (op === "list" ? `${prefix ? `${prefix}_` : ""}list_${pluralize(resource.name)}` : `${prefix ? `${prefix}_` : ""}${op}_${resource.name}`);
+		tools.push({
+			name,
+			description: config.descriptions?.[op] ?? defaultDescription(op, resource.displayName, hasSoftDelete, {
+				filterableFields,
+				allowedOperators,
+				sortableFields
+			}),
+			annotations: ANNOTATIONS[op],
+			inputSchema: buildInputSchema(op, fieldRules, {
+				hiddenFields,
+				readonlyFields,
+				extraHideFields: config.hideFields,
+				filterableFields
+			}),
+			handler: createHandler(op, controller, resource.name)
+		});
+	}
+	for (const route of resource.additionalRoutes ?? []) {
+		const mcpHandler = route.mcpHandler;
+		if (!route.wrapHandler && !mcpHandler) continue;
+		if (!mcpHandler && ![
+			"POST",
+			"PUT",
+			"PATCH",
+			"DELETE"
+		].includes(route.method)) continue;
+		const opName = route.operation ?? slugifyRoute(route.method, route.path);
+		const hasId = route.path.includes(":id");
+		const inputShape = {};
+		if (hasId) inputShape.id = z.string().describe("Resource ID");
+		if (mcpHandler) tools.push({
+			name: prefix ? `${prefix}_${opName}_${resource.name}` : `${opName}_${resource.name}`,
+			description: route.summary ?? route.description ?? `${opName} on ${resource.displayName}`,
+			annotations: { openWorldHint: true },
+			inputSchema: inputShape,
+			handler: async (input, _ctx) => {
+				try {
+					return await mcpHandler(input);
+				} catch (err) {
+					return {
+						content: [{
+							type: "text",
+							text: `Error: ${err instanceof Error ? err.message : String(err)}`
+						}],
+						isError: true
+					};
+				}
+			}
+		});
+		else tools.push({
+			name: prefix ? `${prefix}_${opName}_${resource.name}` : `${opName}_${resource.name}`,
+			description: route.summary ?? route.description ?? `${opName} on ${resource.displayName}`,
+			annotations: { openWorldHint: true },
+			inputSchema: inputShape,
+			handler: createAdditionalRouteHandler(route, controller, hasId)
+		});
+	}
+	return tools;
+}
+function buildInputSchema(op, fieldRules, opts) {
+	switch (op) {
+		case "list": return fieldRulesToZod(fieldRules, {
+			mode: "list",
+			...opts
+		});
+		case "get": return { id: z.string().describe("Resource ID") };
+		case "create": return fieldRulesToZod(fieldRules, {
+			mode: "create",
+			...opts
+		});
+		case "update": return {
+			id: z.string().describe("Resource ID"),
+			...fieldRulesToZod(fieldRules, {
+				mode: "update",
+				...opts
+			})
+		};
+		case "delete": return { id: z.string().describe("Resource ID") };
+	}
+}
+function createHandler(op, controller, resourceName) {
+	const ctrl = controller;
+	return async (input, ctx) => {
+		try {
+			const method = ctrl[op];
+			if (typeof method !== "function") return {
+				content: [{
+					type: "text",
+					text: `Operation "${op}" not available on ${resourceName}`
+				}],
+				isError: true
+			};
+			return toCallToolResult(await method(buildRequestContext(input, ctx.session, op)));
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			ctx.log("error", `${resourceName}.${op}: ${msg}`).catch(() => {});
+			return {
+				content: [{
+					type: "text",
+					text: `Error: ${msg}`
+				}],
+				isError: true
+			};
+		}
+	};
+}
+function createAdditionalRouteHandler(route, controller, hasId) {
+	const ctrl = controller;
+	const handlerName = typeof route.handler === "string" ? route.handler : route.operation ?? slugifyRoute(route.method, route.path);
+	return async (input, ctx) => {
+		try {
+			const method = ctrl[handlerName];
+			if (typeof method !== "function") return {
+				content: [{
+					type: "text",
+					text: `Handler "${handlerName}" not found on controller`
+				}],
+				isError: true
+			};
+			return toCallToolResult(await method(buildRequestContext(input, ctx.session, hasId ? "update" : "create")));
+		} catch (err) {
+			return {
+				content: [{
+					type: "text",
+					text: `Error: ${err instanceof Error ? err.message : String(err)}`
+				}],
+				isError: true
+			};
+		}
+	};
+}
+function toCallToolResult(result) {
+	if (!result.success) return {
+		content: [{
+			type: "text",
+			text: result.error ?? "Operation failed"
+		}],
+		isError: true
+	};
+	const output = result.meta ? {
+		data: result.data,
+		...result.meta
+	} : result.data;
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(output, null, 2)
+	}] };
+}
+function defaultDescription(op, displayName, softDelete, queryMeta) {
+	const name = displayName.toLowerCase();
+	switch (op) {
+		case "list": {
+			const parts = [`List ${pluralize(name)} with optional filters and pagination.`];
+			if (queryMeta?.filterableFields?.length) parts.push(`Filterable fields: ${queryMeta.filterableFields.join(", ")}.`);
+			if (queryMeta?.allowedOperators?.length) parts.push(`Filter operators: ${queryMeta.allowedOperators.join(", ")} (use field[op]=value syntax).`);
+			if (queryMeta?.sortableFields?.length) parts.push(`Sortable fields: ${queryMeta.sortableFields.join(", ")}.`);
+			return parts.join(" ");
+		}
+		case "get": return `Get a single ${name} by ID`;
+		case "create": return `Create a new ${name}`;
+		case "update": return `Update an existing ${name} by ID`;
+		case "delete": return softDelete ? `Delete a ${name} by ID (soft delete — marks as deleted, not permanently removed)` : `Delete a ${name} by ID`;
+	}
+}
+function slugifyRoute(method, path) {
+	const clean = path.replace(/:[^/]+/g, "").replace(/^\/+|\/+$/g, "").replace(/\//g, "_");
+	return clean ? `${method.toLowerCase()}_${clean}` : method.toLowerCase();
+}
+/**
+* Auto-create a BaseController from the resource's adapter for MCP use.
+* Called when the resource has an adapter but no controller
+* (e.g. `disableDefaultRoutes: true` skips controller creation in defineResource).
+*/
+function createMcpController(resource) {
+	const repository = resource.adapter?.repository;
+	if (!repository) return void 0;
+	return new BaseController(repository, {
+		resourceName: resource.name,
+		schemaOptions: resource.schemaOptions,
+		tenantField: resource.tenantField,
+		idField: resource.idField,
+		matchesFilter: resource.adapter?.matchesFilter
+	});
+}
+//#endregion
+export { fieldRulesToZod as n, createMcpServer as r, resourceToTools as t };

package/dist/rpc/index.d.mts

@@ -0,0 +1,90 @@
+import { r as CircuitBreakerOptions } from "../circuitBreaker-JP2GdJ4b.mjs";
+
+//#region src/rpc/serviceClient.d.ts
+interface RetryConfig {
+  /** Max retry attempts (not counting initial attempt). Default: 2 */
+  maxRetries?: number;
+  /** Initial backoff delay in ms. Doubles on each retry. Default: 200 */
+  backoffMs?: number;
+  /** Max backoff cap in ms. Default: 5000 */
+  maxBackoffMs?: number;
+  /**
+   * HTTP status codes to retry on. Default: [502, 503, 504, 408, 429]
+   * 4xx errors (except 408, 429) are NOT retried — they are client errors.
+   */
+  retryableStatuses?: number[];
+}
+interface RequestInfo {
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+}
+interface ResponseInfo {
+  method: string;
+  url: string;
+  status: number;
+  durationMs: number;
+  retries: number;
+}
+interface ServiceClientOptions {
+  /** Base URL of the remote Arc service (e.g., 'http://catalog-service:3000') */
+  baseUrl: string;
+  /** Static bearer token, or function that returns one (for rotation) */
+  token?: string | (() => string);
+  /** Organization ID — sent as x-organization-id header */
+  organizationId?: string;
+  /**
+   * Correlation ID for distributed tracing — sent as x-request-id header.
+   * Static string or function (e.g., () => request.id from current request context).
+   */
+  correlationId?: string | (() => string);
+  /** Schema version — sent as x-arc-schema-version header for contract compatibility */
+  schemaVersion?: string;
+  /** Additional headers sent with every request */
+  headers?: Record<string, string>;
+  /** Request timeout in ms (default: 10000) */
+  timeout?: number;
+  /** Retry config for transient failures (default: disabled) */
+  retry?: RetryConfig;
+  /** Circuit breaker config (default: disabled) */
+  circuitBreaker?: Pick<CircuitBreakerOptions, "failureThreshold" | "resetTimeout" | "timeout" | "successThreshold">;
+  /** Health check path (default: '/_health/live' — matches Arc's health plugin) */
+  healthPath?: string;
+  /** Called before each request (for logging, metrics, tracing) */
+  onRequest?: (info: RequestInfo) => void;
+  /** Called after each response (for logging, metrics, tracing) */
+  onResponse?: (info: ResponseInfo) => void;
+}
+interface ResourceClient {
+  /** GET /{resource}s?...query */
+  list(query?: Record<string, unknown>): Promise<ServiceResponse>;
+  /** GET /{resource}s/:id */
+  get(id: string): Promise<ServiceResponse>;
+  /** POST /{resource}s */
+  create(data: Record<string, unknown>): Promise<ServiceResponse>;
+  /** PATCH /{resource}s/:id */
+  update(id: string, data: Record<string, unknown>): Promise<ServiceResponse>;
+  /** DELETE /{resource}s/:id */
+  delete(id: string): Promise<ServiceResponse>;
+  /** POST /{resource}s/:id/action */
+  action(id: string, actionName: string, data?: Record<string, unknown>): Promise<ServiceResponse>;
+}
+interface ServiceResponse<T = any> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  message?: string;
+  status?: number;
+  meta?: Record<string, unknown>;
+}
+interface ServiceClient {
+  /** Get a typed resource client for CRUD + actions */
+  resource(name: string): ResourceClient;
+  /** Raw call to any path (for non-resource endpoints) */
+  call(method: string, path: string, body?: unknown): Promise<ServiceResponse>;
+  /** Health check — returns true if service is reachable */
+  health(): Promise<boolean>;
+}
+declare function createServiceClient(options: ServiceClientOptions): ServiceClient;
+//#endregion
+export { type RequestInfo, type ResourceClient, type ResponseInfo, type RetryConfig, type ServiceClient, type ServiceClientOptions, type ServiceResponse, createServiceClient };