devframe 0.7.16 → 0.8.1

package/dist/diagnostics-B5-qHeqD.mjs

@@ -0,0 +1,94 @@
+import { t as devframeReporter } from "./diagnostics-reporter-CsIG85Q5.mjs";
+import { defineDiagnostics } from "nostics";
+//#region src/node/diagnostics.ts
+const diagnostics = defineDiagnostics({
+	docsBase: "https://devfra.me/errors",
+	reporters: [devframeReporter],
+	codes: {
+		DF0006: { why: (p) => `RPC function "${p.name}" is not registered` },
+		DF0007: { why: "AsyncLocalStorage is not set, it likely to be an internal bug of the Devframe foundation" },
+		DF0008: { why: (p) => `distDir ${p.distDir} does not exist` },
+		DF0012: { why: (p) => `Failed to parse storage file: ${p.filepath}, falling back to defaults.` },
+		DF0013: { why: (p) => `Shared state of "${p.key}" is not found, please provide an initial value for the first time` },
+		DF0014: {
+			why: (p) => `RPC function "${p.name}" has an invalid \`agent\` field — \`description\` must be a non-empty string.`,
+			fix: "Provide a short description (~1–3 sentences) explaining what the tool does and when agents should invoke it."
+		},
+		DF0015: {
+			why: (p) => `Agent tool "${p.id}" is already registered.`,
+			fix: "Tool ids must be unique across RPC functions with an `agent` field and tools registered via `ctx.agent.registerTool()`."
+		},
+		DF0016: { why: (p) => `Agent resource "${p.id}" is already registered.` },
+		DF0017: { why: (p) => `Failed to start MCP server (${p.transport}): ${p.reason}` },
+		DF0029: {
+			why: (p) => `Stream "${p.channel}#${p.id}" dropped ${p.dropped} chunk(s) after exceeding the client high-water mark.`,
+			fix: "The consumer is too slow for the producer. Raise `highWaterMark` on the subscription, slow the producer, or batch chunks."
+		},
+		DF0030: {
+			why: (p) => `Stream "${p.channel}#${p.id}" is unknown — no producer has called \`channel.start({ id: "${p.id}" })\`.`,
+			fix: "Ensure the server-side producer is running before clients subscribe, or check for typos in the stream id."
+		},
+		DF0031: {
+			why: (p) => `Cannot write to closed stream "${p.channel}#${p.id}".`,
+			fix: "Track the producer lifecycle — guard writes with the `stream.signal.aborted` flag."
+		},
+		DF0032: {
+			why: (p) => `Streaming channel "${p.channel}" is already registered.`,
+			fix: "Each channel name must be unique within a context. Pick a different name or reuse the existing channel handle."
+		},
+		DF0033: {
+			why: (p) => `Failed to start dev RPC bridge for "${p.id}": ${p.reason}`,
+			fix: "Verify the bridge port is free and the devframe setup function does not throw. Pin a port via `cli.port` / `cli.portRange` on the definition, or via `devMiddleware.port` on `viteDevBridge`."
+		},
+		DF0034: {
+			why: (p) => `Scoped RPC registration for namespace "${p.namespace}" received an already-namespaced function name "${p.name}".`,
+			fix: "A scoped context auto-namespaces ids. Pass a bare name without a \":\" separator (e.g. `register({ name: \"get-cwd\" })`), or use the unscoped `ctx.base.rpc.register` for a fully-qualified name."
+		},
+		DF0035: {
+			why: (p) => `Failed to persist storage file: ${p.filepath}`,
+			fix: "Check that the storage directory is writable and has free space."
+		},
+		DF0036: {
+			why: (p) => `RPC call to "${p.name}" was rejected: the caller is not authorized.`,
+			fix: "Complete the auth handshake (or connect with a static/pre-shared token) before calling a trusted method. Untrusted callers may only call `anonymous:`-prefixed methods — see `isAnonymousRpcMethod`."
+		},
+		DF0037: {
+			why: (p) => `A service is already provided under "${p.id}".`,
+			fix: "Service ids are unique per context. Revoke the existing provider first (the `provide()` call returns a revoke function), or namespace the id with your plugin id to avoid collisions."
+		},
+		DF0042: {
+			why: (p) => `"${p.id}" declares \`capabilities.build: false\` — its static export is not meaningful (writes are excluded and any live-served data won't be there).`,
+			fix: "Pass `{ force: true }` to `createBuild()` if the degraded export is still useful to you, or drop `capabilities.build: false` on the definition."
+		},
+		DF0045: {
+			why: (p) => `Failed to update the devframe instance registry at "${p.file}": ${p.reason}`,
+			fix: "Discovery tooling (`devframe connect`) will not see this instance. Check that the registry directory is writable, point `DEVFRAME_INSTANCES_DIR` at a writable directory, or set `DEVFRAME_DISABLE_INSTANCE_REGISTRY=1` to opt out of registration."
+		},
+		DF0046: {
+			why: (p) => `\`devframe connect\` requires the optional peer dependency @modelcontextprotocol/server: ${p.reason}`,
+			fix: "Install it next to devframe (e.g. `npm install @modelcontextprotocol/server`) and run `devframe connect` again."
+		},
+		DF0047: {
+			why: (p) => `Agent tool "${p.id}" is hidden from the MCP surface: its wire name "${p.name}" collides with the tool "${p.existing}".`,
+			fix: "Wire names derive from tool ids (characters outside [a-zA-Z0-9_-] become \"_\"). Rename one of the two ids so they sanitize to distinct names."
+		},
+		DF0048: {
+			why: (p) => `Unknown shared-state key "${p.key}".`,
+			fix: "Call the devframe_state_read tool without arguments to list the available keys, then retry with one of them."
+		},
+		DF0049: {
+			why: "The devframe_connect_call-tool tool requires { port: number, tool: string }.",
+			fix: "Call devframe_connect_list-instances to get the port and tool names, then retry."
+		},
+		DF0050: {
+			why: (p) => `No running devframe instance on port ${p.port}.`,
+			fix: "Call devframe_connect_list-instances for the current instance list — the instance may have stopped or changed port."
+		},
+		DF0051: {
+			why: (p) => `The devframe instance on port ${p.port} has no MCP endpoint.`,
+			fix: "Restart the instance with the --mcp flag (or set `cli.mcp: true` on its definition) to expose its tools, then list instances again."
+		}
+	}
+});
+//#endregion
+export { diagnostics as t };

package/dist/{diagnostics-BXwBQmoN.mjs → diagnostics-hwjXp_UV.mjs}

@@ -26,6 +26,14 @@ const diagnostics = defineDiagnostics({
 		DF0028: {
 			why: (p) => `Function "${p.name}" with type "${p.type}" cannot use \`snapshot: true\`. Only "query" functions support this sugar; "static" functions have equivalent default behavior already.`,
 			fix: "Remove `snapshot: true`, or change the function type to `query`."
+		},
+		DF0043: {
+			why: (p) => `RPC function "${p.name}" received an invalid argument at position ${p.index}: ${p.issues}`,
+			fix: "Pass a value that satisfies the `args` schema declared for this function."
+		},
+		DF0044: {
+			why: (p) => `RPC function "${p.name}" returned a value that failed its \`returns\` schema: ${p.issues}`,
+			fix: "Make the handler return a value that satisfies the `returns` schema, or relax the schema."
 		}
 	}
 });

package/dist/{dump-Cz7yVvsB.mjs → dump-CgZShDRB.mjs}

@@ -1,4 +1,4 @@
-import { t as diagnostics } from "./diagnostics-BXwBQmoN.mjs";
+import { t as diagnostics } from "./diagnostics-hwjXp_UV.mjs";
 import { DEVFRAME_RPC_DUMP_DIRNAME } from "./constants.mjs";
 import { createHash } from "node:crypto";
 //#region ../../node_modules/.pnpm/ohash@2.0.11/node_modules/ohash/dist/shared/ohash.D__AXeF1.mjs
@@ -498,6 +498,70 @@ function getDefinitionsWithDumps(definitions) {
 	return definitions.filter((def) => def.dump !== void 0);
 }
 //#endregion
+//#region src/rpc/validate-io.ts
+/**
+* Run a single [Standard Schema](https://standardschema.dev) validator,
+* awaiting the result when the validator is asynchronous.
+*/
+async function runStandardSchema(schema, value) {
+	const result = schema["~standard"].validate(value);
+	return result instanceof Promise ? await result : result;
+}
+/**
+* Render Standard Schema issues into a single human-readable line for a
+* diagnostic message, prefixing each with its dotted path when present.
+*/
+function formatIssues(issues) {
+	return issues.map((issue) => {
+		const path = issue.path?.map((segment) => typeof segment === "object" ? segment.key : segment).join(".");
+		return path ? `${path}: ${issue.message}` : issue.message;
+	}).join("; ");
+}
+/**
+* Validate positional arguments against their declared schemas. Only
+* indices with a schema are checked; extra arguments pass through
+* untouched. Throws `DF0038` on the first failing argument.
+*
+* Validation guards the payload without rewriting it: the original values
+* are handed to the handler unchanged, so a schema that describes a subset
+* of an object never silently strips the sender's extra fields (and any
+* declared transforms stay a purely type-level concern).
+*
+* @internal
+*/
+async function validateRpcArgs(name, argsSchema, args) {
+	const original = args.slice();
+	if (!argsSchema || argsSchema.length === 0) return original;
+	for (let index = 0; index < argsSchema.length; index++) {
+		const schema = argsSchema[index];
+		if (!schema) continue;
+		const result = await runStandardSchema(schema, args[index]);
+		if (result.issues) throw diagnostics.DF0043({
+			name,
+			index,
+			issues: formatIssues(result.issues)
+		});
+	}
+	return original;
+}
+/**
+* Validate a handler's resolved return value against its declared schema.
+* Throws `DF0039` when the value fails the schema, otherwise returns the
+* original value unchanged (guard-only, never rewriting the payload — see
+* {@link validateRpcArgs}). Passes through when no return schema is set.
+*
+* @internal
+*/
+async function validateRpcReturn(name, returnSchema, value) {
+	if (!returnSchema) return value;
+	const result = await runStandardSchema(returnSchema, value);
+	if (result.issues) throw diagnostics.DF0044({
+		name,
+		issues: formatIssues(result.issues)
+	});
+	return value;
+}
+//#endregion
 //#region src/rpc/handler.ts
 async function getRpcResolvedSetupResult(definition, context) {
 	if (!definition.setup) return {};
@@ -524,10 +588,22 @@ async function getRpcResolvedSetupResult(definition, context) {
 	return await definition.__promise;
 }
 async function getRpcHandler(definition, context) {
-	if (definition.handler) return definition.handler;
-	const result = await getRpcResolvedSetupResult(definition, context);
-	if (!result.handler) throw diagnostics.DF0024({ name: definition.name });
-	return result.handler;
+	let handler = definition.handler;
+	if (!handler) {
+		const result = await getRpcResolvedSetupResult(definition, context);
+		if (!result.handler) throw diagnostics.DF0024({ name: definition.name });
+		handler = result.handler;
+	}
+	const argsSchema = definition.args;
+	const returnSchema = definition.returns;
+	if (!argsSchema && !returnSchema) return handler;
+	const inner = handler;
+	const validating = async (...args) => {
+		const validatedArgs = await validateRpcArgs(definition.name, argsSchema, args);
+		const output = await inner(...validatedArgs);
+		return await validateRpcReturn(definition.name, returnSchema, output);
+	};
+	return validating;
 }
 //#endregion
 //#region src/rpc/dump/static.ts
@@ -607,4 +683,4 @@ async function collectStaticRpcDump(definitions, context) {
 	};
 }
 //#endregion
-export { dumpFunctions as a, serializeDumpError as c, hash as d, createClientFromDump as i, validateDefinition as l, getRpcHandler as n, getDefinitionsWithDumps as o, getRpcResolvedSetupResult as r, reviveDumpError as s, collectStaticRpcDump as t, validateDefinitions as u };
+export { validateRpcReturn as a, getDefinitionsWithDumps as c, validateDefinition as d, validateDefinitions as f, validateRpcArgs as i, reviveDumpError as l, getRpcHandler as n, createClientFromDump as o, hash as p, getRpcResolvedSetupResult as r, dumpFunctions as s, collectStaticRpcDump as t, serializeDumpError as u };