@wild-framework/graph 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wild Framework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @wild-framework/graph
+
+Machine-readable **Project Graph** for [Wild Framework](https://github.com/KhandaSoftware/wild-framework) apps.
+
+A single JSON-serializable model of a running application — providers, routes,
+resources, request schemas, DI bindings, and migrations. It is the source of
+truth that visual builders (Wild Studio) and AI agents render and manipulate.
+
+## Install
+
+```bash
+pnpm add @wild-framework/graph
+```
+
+## Usage
+
+Register `GraphProvider` last (after all feature providers):
+
+```ts
+import { GraphProvider } from "@wild-framework/graph";
+
+GraphProvider.appName = "Shop API";
+GraphProvider.appVersion = "1.0.0";
+
+app.register(GraphProvider); // after feature providers, before/after OpenApi
+```
+
+Then fetch the graph:
+
+```bash
+curl http://localhost:3000/graph.json
+```
+
+Or build it programmatically:
+
+```ts
+import { buildProjectGraph } from "@wild-framework/graph";
+
+const graph = buildProjectGraph(app, router, { name: "Shop API", version: "1.0.0" });
+```
+
+## Graph shape
+
+```jsonc
+{
+  "name": "Shop API",
+  "version": "1.0.0",
+  "providers": [{ "name": "ProductProvider", "index": 8 }],
+  "routes": [{ "method": "get", "path": "/products", "controller": "ProductController", "action": "index", "validator": "CreateProductRequest" }],
+  "resources": [{ "name": "Product", "segment": "products", "routes": [] }],
+  "schemas": [{ "name": "CreateProductRequest", "fields": { "name": "string", "price": "number" } }],
+  "bindings": [{ "token": "ProductService" }],
+  "migrations": [{ "name": "20261010_add_order_index", "applied": true }]
+}
+```
+
+## Design
+
+- Derived from the **live app** (never hand-maintained) via
+  `Application.getRegisteredProviders()`, `Router.getRegisteredRoutes()`, and
+  `Container.listBindings()`.
+- Resources are grouped by first path segment (`/products/:id` → `products`).
+- The graph is **read-only introspection** — the visual builder renders it and
+  maps user actions back to CLI/engine operations (the GUI holds no logic).
+
+## License
+
+MIT

package/dist/build.d.ts

@@ -0,0 +1,19 @@
+import type { Application } from "@wild-framework/core";
+import type { Router } from "@wild-framework/http";
+import type { MigrationStatus } from "@wild-framework/database";
+import type { ProjectGraph } from "./types.js";
+/** Options for building a graph. */
+export interface BuildGraphOptions {
+    name: string;
+    version: string;
+    migrations?: MigrationStatus[];
+}
+/**
+ * Build the Project Graph from a booted application.
+ *
+ * Reads providers (from `Application`), routes + validators (from `Router`),
+ * and bindings (from the `Container`). The result is a plain,
+ * JSON-serializable object.
+ */
+export declare function buildProjectGraph(app: Application, router: Router, options: BuildGraphOptions): ProjectGraph;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,YAAY,CAAC;AAwC5D,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC7B,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,GAC3B,YAAY,CA4Bd"}

package/dist/build.js

@@ -0,0 +1,69 @@
+import { Container } from "@wild-framework/container";
+import { deriveResources } from "./resources.js";
+/**
+ * Extract field names + simple types from a Zod validator class.
+ *
+ * A validator is a class with a `static schema` (a `z.object`). Reads the
+ * public `.shape` so no internal Zod APIs are used.
+ */
+function schemaFromValidator(validatorName, validator) {
+    const shape = validator?.shape;
+    const fields = {};
+    if (shape && typeof shape === "object") {
+        for (const [key, def] of Object.entries(shape)) {
+            fields[key] = zodTypeName(def);
+        }
+    }
+    return { name: validatorName, fields };
+}
+/** Map a Zod type instance to a simple type name. */
+function zodTypeName(def) {
+    const t = def;
+    const typeName = t?._def?.typeName;
+    switch (typeName) {
+        case "ZodString":
+            return "string";
+        case "ZodNumber":
+            return "number";
+        case "ZodBoolean":
+            return "boolean";
+        case "ZodArray":
+            return "array";
+        default:
+            return "unknown";
+    }
+}
+/**
+ * Build the Project Graph from a booted application.
+ *
+ * Reads providers (from `Application`), routes + validators (from `Router`),
+ * and bindings (from the `Container`). The result is a plain,
+ * JSON-serializable object.
+ */
+export function buildProjectGraph(app, router, options) {
+    const registered = router.getRegisteredRoutes();
+    const container = app.resolve(Container);
+    const schemas = [];
+    for (const route of registered) {
+        if (route.validator && route.validatorName) {
+            schemas.push(schemaFromValidator(route.validatorName, route.validator));
+        }
+    }
+    return {
+        name: options.name,
+        version: options.version,
+        providers: app.getRegisteredProviders().map((name, index) => ({ name, index })),
+        routes: registered.map((r) => ({
+            method: r.method,
+            path: r.path,
+            controller: r.action?.controller?.name,
+            action: r.action?.method,
+            validator: r.validatorName,
+        })),
+        resources: deriveResources(registered),
+        schemas,
+        bindings: container.listBindings().map((token) => ({ token })),
+        migrations: options.migrations ?? [],
+    };
+}
+//# sourceMappingURL=build.js.map

package/dist/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAItD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,aAAqB,EAAE,SAAkB;IAClE,MAAM,KAAK,GAAI,SAAwD,EAAE,KAAK,CAAC;IAE/E,MAAM,MAAM,GAA0B,EAAE,CAAC;IACzC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACrC,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7C,MAAM,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;AAC3C,CAAC;AAED,qDAAqD;AACrD,SAAS,WAAW,CAAC,GAAY;IAC7B,MAAM,CAAC,GAAG,GAA8C,CAAC;IACzD,MAAM,QAAQ,GAAG,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC;IACnC,QAAQ,QAAQ,EAAE,CAAC;QACf,KAAK,WAAW;YACZ,OAAO,QAAQ,CAAC;QACpB,KAAK,WAAW;YACZ,OAAO,QAAQ,CAAC;QACpB,KAAK,YAAY;YACb,OAAO,SAAS,CAAC;QACrB,KAAK,UAAU;YACX,OAAO,OAAO,CAAC;QACnB;YACI,OAAO,SAAS,CAAC;IACzB,CAAC;AACL,CAAC;AASD;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC7B,GAAgB,EAChB,MAAc,EACd,OAA0B;IAE1B,MAAM,UAAU,GAAG,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAEhD,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAY,SAAS,CAAC,CAAC;IAEpD,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;YACzC,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;QAC5E,CAAC;IACL,CAAC;IAED,OAAO;QACH,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,SAAS,EAAE,GAAG,CAAC,sBAAsB,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/E,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC3B,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,UAAU,EAAG,CAAC,CAAC,MAAM,EAAE,UAAuD,EAAE,IAAI;YACpF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM;YACxB,SAAS,EAAE,CAAC,CAAC,aAAa;SAC7B,CAAC,CAAC;QACH,SAAS,EAAE,eAAe,CAAC,UAAU,CAAC;QACtC,OAAO;QACP,QAAQ,EAAE,SAAS,CAAC,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9D,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,EAAE;KACvC,CAAC;AACN,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { buildProjectGraph, type BuildGraphOptions } from "./build.js";
+export { deriveResources, singularize, toPascal, segmentOf } from "./resources.js";
+export { GraphProvider, type GraphProviderOptions } from "./provider.js";
+export type { ProjectGraph, GraphProviderEntry, GraphRoute, GraphResource, GraphSchema, GraphBinding, GraphMigration, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACzE,YAAY,EACR,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACV,aAAa,EACb,WAAW,EACX,YAAY,EACZ,cAAc,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { buildProjectGraph } from "./build.js";
+export { deriveResources, singularize, toPascal, segmentOf } from "./resources.js";
+export { GraphProvider } from "./provider.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAA0B,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EAAE,aAAa,EAA6B,MAAM,eAAe,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,37 @@
+import type { Provider, Application } from "@wild-framework/core";
+/**
+ * Options for GraphProvider.
+ */
+export interface GraphProviderOptions {
+    /** Application name. Defaults to "Wild Framework". */
+    appName?: string;
+    /** Application version. Defaults to "0.1.0". */
+    appVersion?: string;
+    /** HTTP path where the graph JSON is served. Default "/graph.json". */
+    path?: string;
+}
+/**
+ * Builds the Project Graph at boot and serves it over HTTP.
+ *
+ * - `register()`: binds a lazy `ProjectGraph` accessor into the container.
+ * - `boot()`: builds the graph and serves `GET /graph.json` via the Router.
+ *
+ * Register this provider AFTER all feature providers (like OpenApiProvider),
+ * so the route list is complete.
+ *
+ * This is the single introspection endpoint the Wild Studio visual builder
+ * and AI agents read — the GUI never holds its own model.
+ */
+export declare class GraphProvider implements Provider {
+    /** Application name. */
+    static appName: string;
+    /** Application version. */
+    static appVersion: string;
+    /** HTTP path where the graph JSON is served. Default "/graph.json". */
+    static path: string;
+    private app;
+    private graph;
+    register(app: Application): void;
+    boot(app: Application): Promise<void>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAMlE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,YAAW,QAAQ;IAC1C,wBAAwB;IACxB,MAAM,CAAC,OAAO,SAAoB;IAClC,2BAA2B;IAC3B,MAAM,CAAC,UAAU,SAAW;IAC5B,uEAAuE;IACvE,MAAM,CAAC,IAAI,SAAiB;IAE5B,OAAO,CAAC,GAAG,CAA0B;IACrC,OAAO,CAAC,KAAK,CAA2B;IAExC,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAO1B,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAU9C"}

package/dist/provider.js

@@ -0,0 +1,41 @@
+import { Container } from "@wild-framework/container";
+import { Router } from "@wild-framework/http";
+import { buildProjectGraph } from "./build.js";
+/**
+ * Builds the Project Graph at boot and serves it over HTTP.
+ *
+ * - `register()`: binds a lazy `ProjectGraph` accessor into the container.
+ * - `boot()`: builds the graph and serves `GET /graph.json` via the Router.
+ *
+ * Register this provider AFTER all feature providers (like OpenApiProvider),
+ * so the route list is complete.
+ *
+ * This is the single introspection endpoint the Wild Studio visual builder
+ * and AI agents read — the GUI never holds its own model.
+ */
+export class GraphProvider {
+    /** Application name. */
+    static appName = "Wild Framework";
+    /** Application version. */
+    static appVersion = "0.1.0";
+    /** HTTP path where the graph JSON is served. Default "/graph.json". */
+    static path = "/graph.json";
+    app;
+    graph;
+    register(app) {
+        this.app = app;
+        const container = app.resolve(Container);
+        // Bind the graph lazily — built on first resolve (after boot).
+        container.singleton("ProjectGraph", () => this.graph);
+    }
+    async boot(app) {
+        const router = app.resolve(Router);
+        this.graph = buildProjectGraph(app, router, {
+            name: GraphProvider.appName,
+            version: GraphProvider.appVersion,
+        });
+        // Serve the graph over HTTP for visual builders / agents.
+        router.get(GraphProvider.path, (_req, res) => res.json(this.graph));
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAe/C;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,aAAa;IACtB,wBAAwB;IACxB,MAAM,CAAC,OAAO,GAAG,gBAAgB,CAAC;IAClC,2BAA2B;IAC3B,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC;IAC5B,uEAAuE;IACvE,MAAM,CAAC,IAAI,GAAG,aAAa,CAAC;IAEpB,GAAG,CAA0B;IAC7B,KAAK,CAA2B;IAExC,QAAQ,CAAC,GAAgB;QACrB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzC,+DAA+D;QAC/D,SAAS,CAAC,SAAS,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAgB;QACvB,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAS,MAAM,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK,GAAG,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE;YACxC,IAAI,EAAE,aAAa,CAAC,OAAO;YAC3B,OAAO,EAAE,aAAa,CAAC,UAAU;SACpC,CAAC,CAAC;QAEH,0DAA0D;QAC1D,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,CAAC"}

package/dist/resources.d.ts

@@ -0,0 +1,18 @@
+import type { RegisteredRoute } from "@wild-framework/http";
+import type { GraphResource } from "./types.js";
+/** PascalCase a kebab/lowercase string: "products" → "Products"; "user" → "User". */
+export declare function toPascal(value: string): string;
+/** Singularize a simple plural ("products" → "product"). */
+export declare function singularize(word: string): string;
+/** First non-empty path segment of a route, or "root". */
+export declare function segmentOf(path: string): string;
+/**
+ * Derive resources from a route list by grouping on the first path segment.
+ *
+ * Dynamic segments (`:id`) are dropped from the group key so `/products` and
+ * `/products/:id` belong to the same resource. Infrastructure routes
+ * (docs, openapi.json, graph.json, health) are excluded — they are not
+ * domain resources.
+ */
+export declare function deriveResources(routes: RegisteredRoute[]): GraphResource[];
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,YAAY,CAAC;AAE5D,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM9C;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,0DAA0D;AAC1D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG9C;AAqBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE,CAgB1E"}

package/dist/resources.js

@@ -0,0 +1,63 @@
+/** PascalCase a kebab/lowercase string: "products" → "Products"; "user" → "User". */
+export function toPascal(value) {
+    return value
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("");
+}
+/** Singularize a simple plural ("products" → "product"). */
+export function singularize(word) {
+    if (word.endsWith("ies"))
+        return word.slice(0, -3) + "y";
+    if (word.endsWith("s") && !word.endsWith("ss"))
+        return word.slice(0, -1);
+    return word;
+}
+/** First non-empty path segment of a route, or "root". */
+export function segmentOf(path) {
+    const parts = path.split("/").filter(Boolean);
+    return parts[0] ?? "root";
+}
+function toGraphRoute(route) {
+    const ctor = route.action?.controller;
+    return {
+        method: route.method,
+        path: route.path,
+        controller: ctor?.name,
+        action: route.action?.method,
+        validator: route.validatorName,
+    };
+}
+/** Well-known infrastructure paths that are not domain resources. */
+const INFRA_SEGMENTS = new Set([
+    "docs",
+    "openapi.json",
+    "graph.json",
+    "health",
+]);
+/**
+ * Derive resources from a route list by grouping on the first path segment.
+ *
+ * Dynamic segments (`:id`) are dropped from the group key so `/products` and
+ * `/products/:id` belong to the same resource. Infrastructure routes
+ * (docs, openapi.json, graph.json, health) are excluded — they are not
+ * domain resources.
+ */
+export function deriveResources(routes) {
+    const groups = new Map();
+    for (const route of routes) {
+        const segment = segmentOf(route.path);
+        if (INFRA_SEGMENTS.has(segment))
+            continue;
+        const existing = groups.get(segment) ?? [];
+        existing.push(toGraphRoute(route));
+        groups.set(segment, existing);
+    }
+    return [...groups.entries()].map(([segment, groupRoutes]) => ({
+        name: toPascal(singularize(segment)),
+        segment,
+        routes: groupRoutes,
+    }));
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAGA,qFAAqF;AACrF,MAAM,UAAU,QAAQ,CAAC,KAAa;IAClC,OAAO,KAAK;SACP,KAAK,CAAC,eAAe,CAAC;SACtB,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAC3D,IAAI,CAAC,EAAE,CAAC,CAAC;AAClB,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,WAAW,CAAC,IAAY;IACpC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;IACzD,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACzE,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,SAAS,CAAC,IAAY;IAClC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9C,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC;AAC9B,CAAC;AAED,SAAS,YAAY,CAAC,KAAsB;IACxC,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,EAAE,UAAsD,CAAC;IAClF,OAAO;QACH,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,UAAU,EAAE,IAAI,EAAE,IAAI;QACtB,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM;QAC5B,SAAS,EAAE,KAAK,CAAC,aAAa;KACjC,CAAC;AACN,CAAC;AAED,qEAAqE;AACrE,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC3B,MAAM;IACN,cAAc;IACd,YAAY;IACZ,QAAQ;CACX,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAAyB;IACrD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAwB,CAAC;IAE/C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,SAAS;QAC1C,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAC3C,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1D,IAAI,EAAE,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACpC,OAAO;QACP,MAAM,EAAE,WAAW;KACtB,CAAC,CAAC,CAAC;AACR,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The Wild Framework Project Graph — a machine-readable model of a running
+ * application.
+ *
+ * This is the single source of truth that visual builders (Wild Studio) and
+ * AI agents render and manipulate. It is JSON-serializable and always
+ * derived from the live app, never hand-maintained.
+ */
+export interface ProjectGraph {
+    /** Application name. */
+    name: string;
+    /** Application version. */
+    version: string;
+    /** Providers, in registration order. */
+    providers: GraphProviderEntry[];
+    /** Every registered HTTP route. */
+    routes: GraphRoute[];
+    /** Resources derived from routes (grouped by first path segment). */
+    resources: GraphResource[];
+    /** Request schemas (from Zod validators), keyed by validator class name. */
+    schemas: GraphSchema[];
+    /** Container bindings. */
+    bindings: GraphBinding[];
+    /** Migrations and their applied state. */
+    migrations: GraphMigration[];
+}
+/** A registered provider. */
+export interface GraphProviderEntry {
+    /** Class name, e.g. "ProductProvider". */
+    name: string;
+    /** Zero-based registration order. */
+    index: number;
+}
+/** A registered HTTP route. */
+export interface GraphRoute {
+    method: "get" | "post" | "put" | "patch" | "delete";
+    path: string;
+    /** Controller class name (from `action()`), if any. */
+    controller?: string;
+    /** Controller method name, if any. */
+    action?: string;
+    /** Validator class name, if any. */
+    validator?: string;
+}
+/** A resource — a group of routes sharing a first path segment. */
+export interface GraphResource {
+    /** PascalCase singular name, e.g. "Product". */
+    name: string;
+    /** URL segment, e.g. "products". */
+    segment: string;
+    /** Routes belonging to this resource. */
+    routes: GraphRoute[];
+}
+/** A request schema (from a Zod validator class). */
+export interface GraphSchema {
+    /** Validator class name, e.g. "CreateProductRequest". */
+    name: string;
+    /** Field name → simple type. */
+    fields: Record<string, "string" | "number" | "boolean" | "array" | "unknown">;
+}
+/** A container binding. */
+export interface GraphBinding {
+    /** Token name (class name, string, or symbol). */
+    token: string;
+}
+/** A migration + applied state. */
+export interface GraphMigration {
+    name: string;
+    applied: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IACzB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,mCAAmC;IACnC,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,qEAAqE;IACrE,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,4EAA4E;IAC5E,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,0BAA0B;IAC1B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,0CAA0C;IAC1C,UAAU,EAAE,cAAc,EAAE,CAAC;CAChC;AAED,6BAA6B;AAC7B,MAAM,WAAW,kBAAkB;IAC/B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,+BAA+B;AAC/B,MAAM,WAAW,UAAU;IACvB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC1B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,MAAM,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,qDAAqD;AACrD,MAAM,WAAW,WAAW;IACxB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;CACjF;AAED,2BAA2B;AAC3B,MAAM,WAAW,YAAY;IACzB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@wild-framework/graph",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Sphah",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KhandaSoftware/wild-framework.git"
+  },
+  "description": "Machine-readable project graph (introspection) for Wild Framework apps — for visual builders and AI agents.",
+  "keywords": [
+    "wild",
+    "framework",
+    "graph",
+    "introspection",
+    "visual-builder",
+    "agents"
+  ],
+  "dependencies": {
+    "@wild-framework/core": "0.2.0",
+    "@wild-framework/container": "0.2.0",
+    "@wild-framework/database": "0.2.0",
+    "@wild-framework/http": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}