@nifrajs/core 1.3.1 → 1.4.0

package/dist/index.d.ts

@@ -11,10 +11,11 @@
  * (it shipped at "0.0.0" through 1.0.0 before those guards existed). Kept narrow (`as const`) so
  * consumers can pin it at the type level — see `test/version.test-d.ts`.
  */
-export declare const VERSION: "1.3.1";
+export declare const VERSION: "1.4.0";
 export type Version = typeof VERSION;
 export { FrameworkError, RouteConfigError, type RouteConfigErrorCode } from "./errors.js";
 export { FRAMEWORK_NAME, type FrameworkName } from "./internal/brand.js";
+export * from "./reflection.js";
 export { METHODS, type Method, Router, type RouterMatch } from "./router/router.js";
 export type { InferInput, InferOutput, StandardIssue, StandardResult, StandardSchemaV1, StandardTypes, ValidationOutcome, } from "./schema/standard.js";
 export { validateStandard } from "./schema/standard.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,EAAG,OAAgB,CAAA;AAEvC,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAA;AAEpC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxE,OAAO,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACnF,YAAY,EACV,UAAU,EACV,WAAW,EACX,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,MAAM,EACN,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,OAAO,GACR,MAAM,UAAU,CAAA;AACjB,YAAY,EACV,OAAO,EACP,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,cAAc,EACd,KAAK,WAAW,EAChB,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,KAAK,aAAa,EAClB,YAAY,EACZ,eAAe,EACf,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,eAAe,EACf,YAAY,GACb,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EACL,KAAK,SAAS,EACd,KAAK,0BAA0B,EAC/B,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,MAAM,EACN,KAAK,aAAa,EAClB,MAAM,EACN,KAAK,eAAe,EACpB,cAAc,GACf,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,SAAS,EACd,GAAG,GACJ,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,EAAG,OAAgB,CAAA;AAEvC,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAA;AAEpC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxE,cAAc,iBAAiB,CAAA;AAC/B,OAAO,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACnF,YAAY,EACV,UAAU,EACV,WAAW,EACX,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAClB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,MAAM,EACN,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,OAAO,GACR,MAAM,UAAU,CAAA;AACjB,YAAY,EACV,OAAO,EACP,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,cAAc,EACd,KAAK,WAAW,EAChB,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,WAAW,GACjB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,KAAK,aAAa,EAClB,YAAY,EACZ,eAAe,EACf,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,eAAe,EACf,YAAY,GACb,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EACL,KAAK,SAAS,EACd,KAAK,0BAA0B,EAC/B,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,MAAM,EACN,KAAK,aAAa,EAClB,MAAM,EACN,KAAK,eAAe,EACpB,cAAc,GACf,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,SAAS,EACd,GAAG,GACJ,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/index.js

@@ -11,9 +11,10 @@
  * (it shipped at "0.0.0" through 1.0.0 before those guards existed). Kept narrow (`as const`) so
  * consumers can pin it at the type level — see `test/version.test-d.ts`.
  */
-export const VERSION = "1.3.1";
+export const VERSION = "1.4.0";
 export { FrameworkError, RouteConfigError } from "./errors.js";
 export { FRAMEWORK_NAME } from "./internal/brand.js";
+export * from "./reflection.js";
 export { METHODS, Router } from "./router/router.js";
 export { validateStandard } from "./schema/standard.js";
 export { robots, sitemap, } from "./seo.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,OAAgB,CAAA;AAIvC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAA6B,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,cAAc,EAAsB,MAAM,qBAAqB,CAAA;AACxE,OAAO,EAAE,OAAO,EAAe,MAAM,EAAoB,MAAM,oBAAoB,CAAA;AAUnF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAGL,MAAM,EAIN,OAAO,GACR,MAAM,UAAU,CAAA;AASjB,OAAO,EAGL,cAAc,EAEd,SAAS,GAKV,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAEL,YAAY,EACZ,eAAe,EACf,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,oBAAoB,EACpB,UAAU,EAIV,eAAe,EACf,YAAY,GACb,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAGL,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAgBlB,MAAM,EAEN,MAAM,EAEN,cAAc,GACf,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAKL,GAAG,GACJ,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAGL,aAAa,GAId,MAAM,qBAAqB,CAAA;AAS5B,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,OAAgB,CAAA;AAIvC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAA6B,MAAM,aAAa,CAAA;AACzF,OAAO,EAAE,cAAc,EAAsB,MAAM,qBAAqB,CAAA;AACxE,cAAc,iBAAiB,CAAA;AAC/B,OAAO,EAAE,OAAO,EAAe,MAAM,EAAoB,MAAM,oBAAoB,CAAA;AAUnF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAGL,MAAM,EAIN,OAAO,GACR,MAAM,UAAU,CAAA;AASjB,OAAO,EAGL,cAAc,EAEd,SAAS,GAKV,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAEL,YAAY,EACZ,eAAe,EACf,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,oBAAoB,EACpB,UAAU,EAIV,eAAe,EACf,YAAY,GACb,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAGL,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAgBlB,MAAM,EAEN,MAAM,EAEN,cAAc,GACf,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAKL,GAAG,GACJ,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAGL,aAAa,GAId,MAAM,qBAAqB,CAAA;AAS5B,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/reflection.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Runtime reflection for schemas and registered routes.
+ *
+ * Standard Schema deliberately standardizes validation, not introspection. This module makes that
+ * distinction explicit: `standard` is present when a value can validate, while `jsonSchema` and
+ * `fields` are present only when the value carries inspectable JSON Schema metadata. The implementation
+ * recognizes Nifra/TypeBox carriers and raw JSON Schema without depending on a validator package.
+ */
+import type { StandardSchemaV1 } from "./schema/standard.js";
+import type { ToolAnnotations } from "./server/server.js";
+/** JSON Schema permits either a schema object or the boolean schemas `true` and `false`. */
+export type JsonSchema = boolean | Readonly<Record<string, unknown>>;
+/** One top-level property of an introspectable object schema. */
+export interface ReflectedSchemaField {
+    readonly name: string;
+    readonly required: boolean;
+    readonly schema: JsonSchema;
+}
+/** Validation and introspection capabilities discovered for one schema-like value. */
+export interface SchemaReflection {
+    /** The Standard Schema validator, when the value implements Standard Schema v1. */
+    readonly standard: StandardSchemaV1 | undefined;
+    /** Raw JSON Schema metadata, when the value exposes it or is itself a raw JSON Schema. */
+    readonly jsonSchema: JsonSchema | undefined;
+    /** Top-level object fields, or `undefined` when the JSON Schema is absent/non-object. */
+    readonly fields: readonly ReflectedSchemaField[] | undefined;
+}
+export interface ReflectedRouteSchema {
+    readonly body?: SchemaReflection;
+    readonly query?: SchemaReflection;
+    readonly response?: SchemaReflection;
+    readonly errors?: Readonly<Record<string, SchemaReflection>>;
+}
+export interface ReflectedRoute {
+    readonly method: string;
+    readonly path: string;
+    readonly schema?: ReflectedRouteSchema;
+    readonly tool?: {
+        readonly name: string;
+        readonly description: string;
+        readonly annotations?: ToolAnnotations;
+    };
+}
+/**
+ * Reflect a Standard Schema, Nifra/TypeBox schema carrier, or raw JSON Schema. Never throws.
+ * Validation-only schemas have `standard` but no `jsonSchema`; raw JSON Schema has the reverse.
+ */
+export declare function reflectSchema(value: unknown): SchemaReflection;
+/**
+ * Safely enumerate and normalize route descriptors from an app or descriptor array. Invalid entries
+ * are ignored; a missing/throwing `routes()` method yields an empty array.
+ */
+export declare function reflectRoutes(source: unknown): readonly ReflectedRoute[];
+//# sourceMappingURL=reflection.d.ts.map

package/dist/reflection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflection.d.ts","sourceRoot":"","sources":["../src/reflection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAEzD,4FAA4F;AAC5F,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAEpE,iEAAiE;AACjE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAC5B;AAED,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,CAAA;IAC/C,0FAA0F;IAC1F,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,CAAA;IAC3C,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,GAAG,SAAS,CAAA;CAC7D;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAA;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAA;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAA;CAC7D;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAA;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;QAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,eAAe,CAAA;KACvC,CAAA;CACF;AAyED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAI9D;AA4CD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,cAAc,EAAE,CAexE"}

package/dist/reflection.js

@@ -0,0 +1,153 @@
+/**
+ * Runtime reflection for schemas and registered routes.
+ *
+ * Standard Schema deliberately standardizes validation, not introspection. This module makes that
+ * distinction explicit: `standard` is present when a value can validate, while `jsonSchema` and
+ * `fields` are present only when the value carries inspectable JSON Schema metadata. The implementation
+ * recognizes Nifra/TypeBox carriers and raw JSON Schema without depending on a validator package.
+ */
+const recordOf = (value) => value !== null && typeof value === "object"
+    ? value
+    : undefined;
+const standardOf = (value) => {
+    const record = recordOf(value);
+    const standard = recordOf(record?.["~standard"]);
+    return standard?.version === 1 && typeof standard.validate === "function"
+        ? value
+        : undefined;
+};
+const jsonSchemaOf = (value, standard) => {
+    const record = recordOf(value);
+    if (record !== undefined && "jsonSchema" in record) {
+        const carried = record.jsonSchema;
+        return normalizeJsonSchema(carried);
+    }
+    // Some Standard Schema implementations (including TypeBox-shaped adapters) expose an object
+    // schema directly rather than through `.jsonSchema`. Only treat an inspectable object shape as
+    // metadata here; validation-library internals are otherwise intentionally opaque.
+    if (standard !== undefined) {
+        return recordOf(record?.properties) !== undefined ? normalizeJsonSchema(record) : undefined;
+    }
+    // A malformed/opaque Standard Schema marker is not raw JSON Schema metadata.
+    if (record !== undefined && "~standard" in record)
+        return undefined;
+    if (typeof value === "boolean" || record !== undefined)
+        return normalizeJsonSchema(value);
+    return undefined;
+};
+/** Strip symbol keys and other non-JSON metadata carried by schema-builder objects. */
+const normalizeJsonSchema = (value) => {
+    if (typeof value === "boolean")
+        return value;
+    if (recordOf(value) === undefined)
+        return undefined;
+    try {
+        const normalized = JSON.parse(JSON.stringify(value));
+        if (typeof normalized === "boolean")
+            return normalized;
+        const record = recordOf(normalized);
+        if (record === undefined)
+            return undefined;
+        // `~standard` is a Standard Schema *validation* marker, never valid JSON Schema. A TypeBox-shaped
+        // carrier (a JSON Schema object that also carries `~standard`, with no separate `.jsonSchema`) would
+        // otherwise leak the marker into emitted OpenAPI / mock / form output.
+        if (!("~standard" in record))
+            return record;
+        const { ["~standard"]: _omitted, ...rest } = record;
+        return rest;
+    }
+    catch {
+        return undefined;
+    }
+};
+const fieldsOf = (schema) => {
+    const record = recordOf(schema);
+    const properties = recordOf(record?.properties);
+    if (properties === undefined)
+        return undefined;
+    const required = new Set(Array.isArray(record?.required)
+        ? record.required.filter((name) => typeof name === "string")
+        : []);
+    const fields = [];
+    for (const [name, property] of Object.entries(properties)) {
+        if (typeof property !== "boolean" && recordOf(property) === undefined)
+            continue;
+        fields.push({ name, required: required.has(name), schema: property });
+    }
+    return fields;
+};
+/**
+ * Reflect a Standard Schema, Nifra/TypeBox schema carrier, or raw JSON Schema. Never throws.
+ * Validation-only schemas have `standard` but no `jsonSchema`; raw JSON Schema has the reverse.
+ */
+export function reflectSchema(value) {
+    const standard = standardOf(value);
+    const jsonSchema = jsonSchemaOf(value, standard);
+    return { standard, jsonSchema, fields: fieldsOf(jsonSchema) };
+}
+const routeCandidates = (source) => {
+    if (Array.isArray(source))
+        return source;
+    const record = recordOf(source);
+    if (typeof record?.routes !== "function")
+        return [];
+    try {
+        const routes = record.routes();
+        return Array.isArray(routes) ? routes : [];
+    }
+    catch {
+        return [];
+    }
+};
+const reflectedRouteSchema = (value) => {
+    const schema = recordOf(value);
+    if (schema === undefined)
+        return undefined;
+    const errors = recordOf(schema.errors);
+    const reflectedErrors = {};
+    if (errors !== undefined) {
+        for (const [status, errorSchema] of Object.entries(errors)) {
+            reflectedErrors[status] = reflectSchema(errorSchema);
+        }
+    }
+    return {
+        ...(schema.body !== undefined ? { body: reflectSchema(schema.body) } : {}),
+        ...(schema.query !== undefined ? { query: reflectSchema(schema.query) } : {}),
+        ...(schema.response !== undefined ? { response: reflectSchema(schema.response) } : {}),
+        ...(Object.keys(reflectedErrors).length > 0 ? { errors: reflectedErrors } : {}),
+    };
+};
+const reflectedTool = (value) => {
+    const tool = recordOf(value);
+    if (typeof tool?.name !== "string" || typeof tool.description !== "string")
+        return undefined;
+    return {
+        name: tool.name,
+        description: tool.description,
+        ...(recordOf(tool.annotations) !== undefined
+            ? { annotations: tool.annotations }
+            : {}),
+    };
+};
+/**
+ * Safely enumerate and normalize route descriptors from an app or descriptor array. Invalid entries
+ * are ignored; a missing/throwing `routes()` method yields an empty array.
+ */
+export function reflectRoutes(source) {
+    const reflected = [];
+    for (const candidate of routeCandidates(source)) {
+        const route = recordOf(candidate);
+        if (typeof route?.method !== "string" || typeof route.path !== "string")
+            continue;
+        const schema = reflectedRouteSchema(route.schema);
+        const tool = reflectedTool(route.tool);
+        reflected.push({
+            method: route.method.toUpperCase(),
+            path: route.path,
+            ...(schema !== undefined ? { schema } : {}),
+            ...(tool !== undefined ? { tool } : {}),
+        });
+    }
+    return reflected;
+}
+//# sourceMappingURL=reflection.js.map

package/dist/reflection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflection.js","sourceRoot":"","sources":["../src/reflection.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/core",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Bun-native, contract-first HTTP framework — the router, server, and route descriptor.",
   "keywords": [
     "bun",
@@ -31,6 +31,11 @@
       "bun": "./src/ws.ts",
       "types": "./dist/ws.d.ts",
       "default": "./dist/ws.js"
+    },
+    "./reflection": {
+      "bun": "./src/reflection.ts",
+      "types": "./dist/reflection.d.ts",
+      "default": "./dist/reflection.js"
     }
   },
   "files": [

package/src/index.ts

@@ -12,12 +12,13 @@
  * (it shipped at "0.0.0" through 1.0.0 before those guards existed). Kept narrow (`as const`) so
  * consumers can pin it at the type level — see `test/version.test-d.ts`.
  */
-export const VERSION = "1.3.1" as const
+export const VERSION = "1.4.0" as const
 
 export type Version = typeof VERSION
 
 export { FrameworkError, RouteConfigError, type RouteConfigErrorCode } from "./errors.ts"
 export { FRAMEWORK_NAME, type FrameworkName } from "./internal/brand.ts"
+export * from "./reflection.ts"
 export { METHODS, type Method, Router, type RouterMatch } from "./router/router.ts"
 export type {
   InferInput,

package/src/reflection.ts

@@ -0,0 +1,193 @@
+/**
+ * Runtime reflection for schemas and registered routes.
+ *
+ * Standard Schema deliberately standardizes validation, not introspection. This module makes that
+ * distinction explicit: `standard` is present when a value can validate, while `jsonSchema` and
+ * `fields` are present only when the value carries inspectable JSON Schema metadata. The implementation
+ * recognizes Nifra/TypeBox carriers and raw JSON Schema without depending on a validator package.
+ */
+
+import type { StandardSchemaV1 } from "./schema/standard.ts"
+import type { ToolAnnotations } from "./server/server.ts"
+
+/** JSON Schema permits either a schema object or the boolean schemas `true` and `false`. */
+export type JsonSchema = boolean | Readonly<Record<string, unknown>>
+
+/** One top-level property of an introspectable object schema. */
+export interface ReflectedSchemaField {
+  readonly name: string
+  readonly required: boolean
+  readonly schema: JsonSchema
+}
+
+/** Validation and introspection capabilities discovered for one schema-like value. */
+export interface SchemaReflection {
+  /** The Standard Schema validator, when the value implements Standard Schema v1. */
+  readonly standard: StandardSchemaV1 | undefined
+  /** Raw JSON Schema metadata, when the value exposes it or is itself a raw JSON Schema. */
+  readonly jsonSchema: JsonSchema | undefined
+  /** Top-level object fields, or `undefined` when the JSON Schema is absent/non-object. */
+  readonly fields: readonly ReflectedSchemaField[] | undefined
+}
+
+export interface ReflectedRouteSchema {
+  readonly body?: SchemaReflection
+  readonly query?: SchemaReflection
+  readonly response?: SchemaReflection
+  readonly errors?: Readonly<Record<string, SchemaReflection>>
+}
+
+export interface ReflectedRoute {
+  readonly method: string
+  readonly path: string
+  readonly schema?: ReflectedRouteSchema
+  readonly tool?: {
+    readonly name: string
+    readonly description: string
+    readonly annotations?: ToolAnnotations
+  }
+}
+
+const recordOf = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  value !== null && typeof value === "object"
+    ? (value as Readonly<Record<string, unknown>>)
+    : undefined
+
+const standardOf = (value: unknown): StandardSchemaV1 | undefined => {
+  const record = recordOf(value)
+  const standard = recordOf(record?.["~standard"])
+  return standard?.version === 1 && typeof standard.validate === "function"
+    ? (value as StandardSchemaV1)
+    : undefined
+}
+
+const jsonSchemaOf = (
+  value: unknown,
+  standard: StandardSchemaV1 | undefined,
+): JsonSchema | undefined => {
+  const record = recordOf(value)
+  if (record !== undefined && "jsonSchema" in record) {
+    const carried = record.jsonSchema
+    return normalizeJsonSchema(carried)
+  }
+  // Some Standard Schema implementations (including TypeBox-shaped adapters) expose an object
+  // schema directly rather than through `.jsonSchema`. Only treat an inspectable object shape as
+  // metadata here; validation-library internals are otherwise intentionally opaque.
+  if (standard !== undefined) {
+    return recordOf(record?.properties) !== undefined ? normalizeJsonSchema(record) : undefined
+  }
+  // A malformed/opaque Standard Schema marker is not raw JSON Schema metadata.
+  if (record !== undefined && "~standard" in record) return undefined
+  if (typeof value === "boolean" || record !== undefined) return normalizeJsonSchema(value)
+  return undefined
+}
+
+/** Strip symbol keys and other non-JSON metadata carried by schema-builder objects. */
+const normalizeJsonSchema = (value: unknown): JsonSchema | undefined => {
+  if (typeof value === "boolean") return value
+  if (recordOf(value) === undefined) return undefined
+  try {
+    const normalized: unknown = JSON.parse(JSON.stringify(value))
+    if (typeof normalized === "boolean") return normalized
+    const record = recordOf(normalized)
+    if (record === undefined) return undefined
+    // `~standard` is a Standard Schema *validation* marker, never valid JSON Schema. A TypeBox-shaped
+    // carrier (a JSON Schema object that also carries `~standard`, with no separate `.jsonSchema`) would
+    // otherwise leak the marker into emitted OpenAPI / mock / form output.
+    if (!("~standard" in record)) return record
+    const { ["~standard"]: _omitted, ...rest } = record
+    return rest
+  } catch {
+    return undefined
+  }
+}
+
+const fieldsOf = (schema: JsonSchema | undefined): readonly ReflectedSchemaField[] | undefined => {
+  const record = recordOf(schema)
+  const properties = recordOf(record?.properties)
+  if (properties === undefined) return undefined
+  const required = new Set(
+    Array.isArray(record?.required)
+      ? record.required.filter((name): name is string => typeof name === "string")
+      : [],
+  )
+  const fields: ReflectedSchemaField[] = []
+  for (const [name, property] of Object.entries(properties)) {
+    if (typeof property !== "boolean" && recordOf(property) === undefined) continue
+    fields.push({ name, required: required.has(name), schema: property as JsonSchema })
+  }
+  return fields
+}
+
+/**
+ * Reflect a Standard Schema, Nifra/TypeBox schema carrier, or raw JSON Schema. Never throws.
+ * Validation-only schemas have `standard` but no `jsonSchema`; raw JSON Schema has the reverse.
+ */
+export function reflectSchema(value: unknown): SchemaReflection {
+  const standard = standardOf(value)
+  const jsonSchema = jsonSchemaOf(value, standard)
+  return { standard, jsonSchema, fields: fieldsOf(jsonSchema) }
+}
+
+const routeCandidates = (source: unknown): readonly unknown[] => {
+  if (Array.isArray(source)) return source
+  const record = recordOf(source)
+  if (typeof record?.routes !== "function") return []
+  try {
+    const routes = record.routes()
+    return Array.isArray(routes) ? routes : []
+  } catch {
+    return []
+  }
+}
+
+const reflectedRouteSchema = (value: unknown): ReflectedRouteSchema | undefined => {
+  const schema = recordOf(value)
+  if (schema === undefined) return undefined
+  const errors = recordOf(schema.errors)
+  const reflectedErrors: Record<string, SchemaReflection> = {}
+  if (errors !== undefined) {
+    for (const [status, errorSchema] of Object.entries(errors)) {
+      reflectedErrors[status] = reflectSchema(errorSchema)
+    }
+  }
+  return {
+    ...(schema.body !== undefined ? { body: reflectSchema(schema.body) } : {}),
+    ...(schema.query !== undefined ? { query: reflectSchema(schema.query) } : {}),
+    ...(schema.response !== undefined ? { response: reflectSchema(schema.response) } : {}),
+    ...(Object.keys(reflectedErrors).length > 0 ? { errors: reflectedErrors } : {}),
+  }
+}
+
+const reflectedTool = (value: unknown): ReflectedRoute["tool"] => {
+  const tool = recordOf(value)
+  if (typeof tool?.name !== "string" || typeof tool.description !== "string") return undefined
+  return {
+    name: tool.name,
+    description: tool.description,
+    ...(recordOf(tool.annotations) !== undefined
+      ? { annotations: tool.annotations as ToolAnnotations }
+      : {}),
+  }
+}
+
+/**
+ * Safely enumerate and normalize route descriptors from an app or descriptor array. Invalid entries
+ * are ignored; a missing/throwing `routes()` method yields an empty array.
+ */
+export function reflectRoutes(source: unknown): readonly ReflectedRoute[] {
+  const reflected: ReflectedRoute[] = []
+  for (const candidate of routeCandidates(source)) {
+    const route = recordOf(candidate)
+    if (typeof route?.method !== "string" || typeof route.path !== "string") continue
+    const schema = reflectedRouteSchema(route.schema)
+    const tool = reflectedTool(route.tool)
+    reflected.push({
+      method: route.method.toUpperCase(),
+      path: route.path,
+      ...(schema !== undefined ? { schema } : {}),
+      ...(tool !== undefined ? { tool } : {}),
+    })
+  }
+  return reflected
+}