proteum 2.1.2 → 2.1.6

package/server/services/router/request/api.ts

@@ -4,6 +4,12 @@
 
 // Core
 
+import { fromJson as errorFromJson } from '@common/errors';
+import {
+    profilerOriginHeader,
+    profilerParentRequestIdHeader,
+    profilerSessionIdHeader,
+} from '@common/dev/profiler';
 import RequestService from './service';
 
 import ApiClientService, {
@@ -21,6 +27,128 @@ import ApiClientService, {
 - SERVICE
 ----------------------------------*/
 export default class ApiClientRequest extends RequestService implements ApiClientService {
+    private isApiFetcher(fetcher: TFetcher | Promise<unknown>): fetcher is TFetcher {
+        return typeof fetcher === 'object' && fetcher !== null && 'method' in fetcher && 'path' in fetcher;
+    }
+
+    private toTraceInspectable(data: unknown) {
+        if (data === null || data === undefined) return data;
+        if (typeof data === 'string' || typeof data === 'number' || typeof data === 'boolean') return data;
+        if (typeof data === 'bigint' || typeof data === 'symbol' || typeof data === 'function') return data;
+        if (typeof data === 'object') return data;
+
+        return undefined;
+    }
+
+    private getTraceCallOrigin() {
+        return this.request.path === '/api' ? 'api-batch-fetcher' as const : 'ssr-fetcher' as const;
+    }
+
+    private createTraceCall({
+        fetcherId,
+        method,
+        path,
+        data,
+        options,
+    }: {
+        fetcherId: string;
+        method: string;
+        path: string;
+        data: unknown;
+        options?: TFetcher['options'];
+    }) {
+        return this.request.router.app.container.Trace.startCall(this.request.id, {
+            origin: this.getTraceCallOrigin(),
+            label: fetcherId,
+            method,
+            path,
+            fetcherId,
+            ...(options?.connected
+                ? {
+                      connectedControllerAccessor: options.connected.controllerAccessor,
+                      connectedProjectNamespace: options.connected.namespace,
+                  }
+                : {}),
+            requestDataKeys: data && typeof data === 'object' ? Object.keys(data as Record<string, unknown>) : [],
+            requestData: this.toTraceInspectable(data),
+        });
+    }
+
+    private buildConnectedRequestHeaders(fetcher: TFetcher) {
+        const headers = new Headers();
+
+        for (const [key, value] of Object.entries(this.request.headers)) {
+            if (!value) continue;
+            if (key === 'content-length' || key === 'host') continue;
+            headers.set(key, value);
+        }
+
+        headers.set('accept', 'application/json');
+
+        if (fetcher.options?.connected) {
+            headers.set(profilerOriginHeader, this.getTraceCallOrigin());
+
+            const profilerSessionId = this.request.headers[profilerSessionIdHeader];
+            if (profilerSessionId) headers.set(profilerSessionIdHeader, profilerSessionId);
+            headers.set(profilerParentRequestIdHeader, this.request.id);
+        }
+
+        return headers;
+    }
+
+    private async resolveConnectedFetcher<TData>(fetcher: TFetcher<TData>) {
+        const connected = fetcher.options?.connected;
+        if (!connected) throw new Error('Connected fetcher metadata is missing.');
+
+        const connectedProject = this.request.router.app.connectedProjects?.[connected.namespace];
+        if (!connectedProject) {
+            throw new Error(`Connected project "${connected.namespace}" is not registered on ${this.request.router.app.identity.identifier}.`);
+        }
+
+        const headers = this.buildConnectedRequestHeaders(fetcher);
+        const url = new URL(fetcher.path, connectedProject.urlInternal).toString();
+        const init: RequestInit = {
+            method: fetcher.method,
+            headers,
+        };
+
+        if (fetcher.data) {
+            if (fetcher.method === 'GET') {
+                const params = new URLSearchParams();
+                for (const [key, value] of Object.entries(fetcher.data)) {
+                    if (value === undefined || value === null) continue;
+                    params.set(key, String(value));
+                }
+
+                return this.fetchConnectedResponse<TData>(`${url}?${params.toString()}`, init);
+            }
+
+            headers.set('content-type', 'application/json');
+            init.body = JSON.stringify(fetcher.data);
+        }
+
+        return this.fetchConnectedResponse<TData>(url, init);
+    }
+
+    private async fetchConnectedResponse<TData>(url: string, init: RequestInit) {
+        const response = await fetch(url, init);
+
+        if (!response.ok) {
+            const contentType = response.headers.get('content-type') || '';
+            const errorPayload = contentType.includes('application/json') ? await response.json() : await response.text();
+            const typedError =
+                typeof errorPayload === 'object' && errorPayload && 'code' in (errorPayload as object)
+                    ? (errorFromJson(errorPayload as any) as Error & { http?: number })
+                    : (new Error(typeof errorPayload === 'string' ? errorPayload : `Connected request failed with ${response.status}.`) as Error & {
+                          http?: number;
+                      });
+            typedError.http = response.status;
+            throw typedError;
+        }
+
+        return (await response.json()) as TData;
+    }
+
     /*----------------------------------
     - HIGH LEVEL
     ----------------------------------*/
@@ -67,39 +195,52 @@ export default class ApiClientRequest extends RequestService implements ApiClien
             if (!fetcher) continue;
 
             // Promise Fetcher (direct call from service method)
-            if ('then' in fetcher) {
+            if (!this.isApiFetcher(fetcher)) {
                 fetchedData[id] = await fetcher;
                 continue;
             }
 
-            const { method, path, data } = fetcher;
+            const { method, path, data, options } = fetcher;
             //this.router.config.debug && console.log(`[api] Resolving from internal api`, method, path, data);
 
             // We don't fetch the already given data
             if (id in fetchedData) continue;
 
-            // Create a children request to resolve the api data
-            const request = this.request.children(method, path, data);
-            const callId = this.request.router.app.container.Trace.startCall(this.request.id, {
-                origin: 'ssr-fetcher',
-                label: id,
-                method,
-                path,
-                fetcherId: id,
-                requestDataKeys: data && typeof data === 'object' ? Object.keys(data) : [],
-                requestData: data,
-            });
+            const callId = this.createTraceCall({ data, fetcherId: id, method, options, path });
 
             try {
-                const response = await request.router.resolve(request);
-                fetchedData[id] = response.data;
+                if (options?.connected) {
+                    fetchedData[id] = await this.resolveConnectedFetcher(fetcher);
+                } else {
+                    const request = this.request.children(method, path, data);
+                    if (callId)
+                        request.traceCall = {
+                            fetcherId: id,
+                            id: callId,
+                            label: id,
+                            origin: this.getTraceCallOrigin(),
+                        };
+
+                    const response = await request.router.resolve(request);
+                    fetchedData[id] = response.data;
+                    this.request.router.app.container.Trace.finishCall(this.request.id, callId, {
+                        statusCode: response.statusCode,
+                        resultKeys:
+                            response.data && typeof response.data === 'object' && !Array.isArray(response.data)
+                                ? Object.keys(response.data as Record<string, unknown>)
+                                : [],
+                        result: response.data as object | string | number | boolean | bigint | symbol | null | undefined,
+                    });
+                    continue;
+                }
+
                 this.request.router.app.container.Trace.finishCall(this.request.id, callId, {
-                    statusCode: response.statusCode,
+                    statusCode: 200,
                     resultKeys:
-                        response.data && typeof response.data === 'object' && !Array.isArray(response.data)
-                            ? Object.keys(response.data as Record<string, unknown>)
+                        fetchedData[id] && typeof fetchedData[id] === 'object' && !Array.isArray(fetchedData[id])
+                            ? Object.keys(fetchedData[id] as Record<string, unknown>)
                             : [],
-                    result: response.data,
+                    result: fetchedData[id] as object | string | number | boolean | bigint | symbol | null | undefined,
                 });
             } catch (error) {
                 const typedError = error instanceof Error ? error : new Error(typeof error === 'string' ? error : 'Unknown error');

package/server/services/router/request/index.ts

@@ -10,6 +10,7 @@ import Bowser from 'bowser';
 
 // Core
 import BaseRequest from '@common/router/request';
+import type { TTraceCallOrigin } from '@common/dev/requestTrace';
 
 // Specific
 import type { HttpMethod, HttpHeaders } from '..';
@@ -35,6 +36,12 @@ const localeFilter = (input: any) => {
 };
 
 export type UploadedFile = File;
+type TRequestTraceCallContext = {
+    fetcherId?: string;
+    id: string;
+    label: string;
+    origin: TTraceCallOrigin;
+};
 
 /*----------------------------------
 - CONTEXTE
@@ -66,6 +73,7 @@ export default class ServerRequest<TRouter extends TAnyRouter = TAnyRouter> exte
 
     // Services
     public api: ApiClient;
+    public traceCall?: TRequestTraceCallContext;
 
     /*----------------------------------
     - INITIALISATION

package/server/services/router/response/index.ts

@@ -141,6 +141,11 @@ export default class ServerResponse<
                 target: getRouteTraceTarget(route as TAnyRoute<TRouterContext<TServerRouter>>),
                 routeId: route.options.id || '',
                 filepath: route.options.filepath || '',
+                source: {
+                    filepath: route.options.filepath || '',
+                    line: route.options.sourceLocation?.line || 0,
+                    column: route.options.sourceLocation?.column || 0,
+                },
                 accept: route.options.accept || '',
             },
             'summary',
@@ -220,7 +225,14 @@ export default class ServerResponse<
         this.app.container.Trace.record(
             this.request.id,
             'setup.options',
-            { optionKeys: Object.keys(options) },
+            {
+                optionKeys: Object.keys(options),
+                source: {
+                    filepath: route.options.filepath || '',
+                    line: route.options.sourceLocation?.line || 0,
+                    column: route.options.sourceLocation?.column || 0,
+                },
+            },
             'resolve',
         );
 
@@ -260,6 +272,11 @@ export default class ServerResponse<
             {
                 target: getRouteTraceTarget(route as TAnyRoute<TRouterContext<TServerRouter>>),
                 routeId: route.options.id || '',
+                source: {
+                    filepath: route.options.filepath || '',
+                    line: route.options.sourceLocation?.line || 0,
+                    column: route.options.sourceLocation?.column || 0,
+                },
                 routerServiceKeys: Object.keys(contextServices),
                 controllerKeys: Object.keys(controllers),
                 customContextKeys: Object.keys(customSsrData as object),
@@ -318,6 +335,11 @@ export default class ServerResponse<
                 chunkId: page.chunkId || '',
                 dataKeys: Object.keys(page.data || {}),
                 data: page.data || {},
+                source: {
+                    filepath: page.route.options.filepath || '',
+                    line: page.route.options.sourceLocation?.line || 0,
+                    column: page.route.options.sourceLocation?.column || 0,
+                },
             },
             'resolve',
         );
@@ -338,6 +360,7 @@ export default class ServerResponse<
         // NOTE: On évite le filtrage sans masque spécifié (performances + risques erreurs)
         if (mask !== undefined) data = await jsonMask(data, mask);
 
+        this.app.container.Trace.setRequestResult(this.request.id, data);
         this.headers['Content-Type'] = 'application/json';
         this.data = (this.request.isVirtual ? data : JSON.stringify(data)) as TData;
         return this.end();

package/server/services/router/response/page/document.tsx

@@ -195,6 +195,11 @@ export default class DocumentRenderer<TRouter extends TServerRouter> {
                 customContextKeys,
                 serializedBytes: Buffer.byteLength(context, 'utf8'),
                 routeCount: this.router.ssrRoutes.length,
+                source: {
+                    filepath: page.route.options.filepath || '',
+                    line: page.route.options.sourceLocation?.line || 0,
+                    column: page.route.options.sourceLocation?.column || 0,
+                },
             },
             'resolve',
         );

package/server/services/router/response/page/index.tsx

@@ -70,6 +70,11 @@ export default class ServerPage<TRouter extends TServerRouter = TServerRouter> e
                 chunkId: this.chunkId || '',
                 title: this.title || '',
                 routeId: this.route.options['id'] || '',
+                source: {
+                    filepath: this.route.options.filepath || '',
+                    line: this.route.options.sourceLocation?.line || 0,
+                    column: this.route.options.sourceLocation?.column || 0,
+                },
             },
             'summary',
         );
@@ -103,6 +108,11 @@ export default class ServerPage<TRouter extends TServerRouter = TServerRouter> e
                     documentLength: document.length,
                     styleCount: this.style.length,
                     scriptCount: this.scripts.length,
+                    source: {
+                        filepath: this.route.options.filepath || '',
+                        line: this.route.options.sourceLocation?.line || 0,
+                        column: this.route.options.sourceLocation?.column || 0,
+                    },
                 },
                 'summary',
             );

package/agents/framework/AGENTS.md

@@ -1,177 +0,0 @@
-# Proteum App Contract
-
-This is the canonical contract for Proteum-based projects. Local project `AGENTS.md` files should add deltas only, not restate these rules.
-
-## First Pass
-
-Inspect apps in this order:
-
-1. Run `npx proteum explain --json` or read `./.proteum/manifest.json`.
-2. Inspect `./server/index.ts`, `./server/config/*.ts`, and the touched files under `./commands`, `./server/controllers`, `./server/services`, `./server/routes`, and `./client/pages`.
-3. Run `npx proteum doctor` if routing or generation looks suspicious.
-4. For request-time issues in dev, read the default port from `PORT` or `./.proteum/manifest.json`; if a server is already running there, inspect `npx proteum trace` output before reproducing the issue or adding logs.
-5. If existing traces are insufficient, run `npx proteum trace arm --capture deep`, reproduce once, then inspect the captured request.
-
-## Non-Negotiable Rules
-
-- Client pages live in `client/pages/**` and register routes with top-level `Router.page(...)` or `Router.error(...)`.
-- Page URLs come from the explicit `Router.page('/path', ...)` call, not from the file path.
-- Callable app APIs live only in `server/controllers/**/*.ts` files that extend `Controller`.
-- Dev-only internal execution lives only in `commands/**/*.ts` files that extend `Commands`.
-- Manual HTTP endpoints live only in `server/routes/**`.
-- Controllers call `this.input(schema)` inside the method body, at most once per method.
-- Request-scoped state lives only on `this.request` and manual-route/router context objects.
-- SSR page data belongs in page `setup`, not in `api.fetch(...)`.
-- Normal service methods do not read request state directly.
-- Do not import runtime values from `@models`.
-- Do not use `@request` runtime globals.
-- Do not use `@app` on the client.
-- Do not edit generated files under `.proteum` by hand.
-- Prefer type inference rooted in the explicit application graph in `server/index.ts`.
-
-## Source Of Truth
-
-Proteum reads:
-
-- `package.json`
-- `identity.yaml`
-- `process.env` via `PORT`, `ENV_*`, `URL`, and `TRACE_*`
-- `server/config/*.ts`
-- `server/index.ts`
-- `server/services/**/service.json`
-- `commands/**/*.ts`
-- `server/controllers/**/*.ts`
-- `server/routes/**/*.ts`
-- `client/pages/**/*.ts(x)`
-- `client/pages/**/_layout/index.tsx`
-- `public/**`
-
-Proteum owns:
-
-- `.proteum/manifest.json`
-- `.proteum/client/*`
-- `.proteum/common/*`
-- `.proteum/server/*`
-
-Project code should consume:
-
-- `@generated/client/*`
-- `@generated/common/*`
-- `@generated/server/*`
-- `@/client/context` as the generated client context entrypoint
-
-Prefer structured CLI surfaces over re-deriving framework facts from source:
-
-- `npx proteum explain --json`
-- `npx proteum doctor --json`
-- `npx proteum trace ...`
-- `npx proteum command ...`
-- `npx proteum create ... --dry-run --json`
-
-Prefer scaffold commands before hand-writing boilerplate:
-
-- Use `npx proteum init <directory> --name <name>` for new apps.
-- Use `npx proteum init ... --dry-run --json` when an agent needs a machine-readable app plan before writing files.
-- Use `npx proteum create page|controller|command|route|service <target>` for new app artifacts before creating the files manually.
-- Use `npx proteum create ... --dry-run --json` when an agent needs a machine-readable artifact plan before writing files.
-
-## File Contracts
-
-### App Bootstrap And Services
-
-- `server/index.ts` default-exports the app `Application` subclass and is the canonical type root.
-- Root services are public class fields instantiated with `new ServiceClass(this, config, this)`.
-- Typed root-service config lives in `server/config/*.ts` via `Services.config(ServiceClass, { ... })`.
-- Router plugins are instantiated explicitly inside the `Router` config `plugins` object.
-- `server/services/**/service.json` plus `server/index.ts` drive generated service typings and manifest entries.
-- Business logic lives in classes that extend `Service` and use `this.services`, `this.models`, and `this.app`.
-- Keep auth, input parsing, locale, cookies, and request-derived values in controllers, then pass explicit typed arguments into services.
-- Split growing features into explicit subservices.
-- `proteum create service ...` scaffolds the service file, its `service.json`, a typed config export under `server/config/*.ts`, and the root registration in `server/index.ts`; review and adapt the generated names before committing.
-
-### Controllers
-
-- Files live under `server/controllers/**/*.ts` and default-export a class extending `Controller`.
-- Methods with bodies become generated client-callable endpoints.
-- Route path comes from the controller file path plus the method name.
-- `export const controllerPath = 'Custom/path'` can override the base path.
-- Generated client calls use `POST`.
-- Prefer `proteum create controller ...` for new controller boilerplate, then adapt the generated method to real service calls.
-
-### Commands
-
-- Files live under `commands/**/*.ts` and default-export a class extending `Commands` from `@server/app/commands`.
-- Methods with bodies become generated dev commands.
-- Command path comes from the file path plus the method name.
-- `export const commandPath = 'Custom/path'` can override the base path.
-- Commands are for dev-only internal execution through `proteum command ...` or the profiler `Commands` tab.
-- Keep command logic internal; do not turn it into a normal controller unless it is a real app API.
-- Prefer `proteum create command ...` for new command boilerplate.
-
-### Client Pages
-
-- Proteum scans page files for top-level `Router.page(...)` and `Router.error(...)` calls.
-- File path controls chunk identity and layout discovery; route path comes from the explicit `Router.page(...)` string.
-- Supported page signatures are `Router.page(path, render)`, `Router.page(path, setup, render)`, `Router.page(path, options, render)`, and `Router.page(path, options, setup, render)`.
-- For new work, prefer `Router.page(path, setup, render)` or `Router.page(path, options, setup, render)`.
-- `setup` returns one flat object. Reserved keys like `_auth`, `_layout`, `_static`, and `_redirectLogged` are route options; all other keys are SSR data.
-- Controller fetchers and promises returned from `setup` resolve before render.
-- `render` consumes resolved setup data and uses generated controller methods from render args or `@/client/context`.
-- Use `api.reload(...)` or `api.set(...)` only when intentionally mutating active page setup state.
-- Error pages use `Router.error(code, options, render)` in `client/pages/_messages/**`.
-- Prefer `proteum create page ...` for new page boilerplate, then review the explicit route path and setup payload.
-
-### Manual Routes
-
-- Use `server/routes/**` only for explicit HTTP behavior that should not be a generated controller action.
-- Good fits include redirects, sitemap or RSS output, OAuth callbacks, webhooks, and public resources with custom semantics.
-- Import server-side app services from `@app` and use route handler context for `request`, `response`, router plugins, and custom router context.
-- If the route is a normal app API, prefer a controller.
-- Prefer `proteum create route ...` for new manual-route boilerplate.
-
-### Models And Aliases
-
-- Use Prisma typings from `@models/types`.
-- Use runtime models through `this.models` or `this.app.Models.client`.
-- Keep Prisma runtime access inside services when possible and prefer explicit `select` or narrow `include`.
-- Do not import runtime values from `@models` or edit generated Prisma client files.
-- Aliases:
-  - `@/client/...`, `@/server/...`, `@/common/...`: app code
-  - `@client/...`, `@server/...`, `@common/...`: Proteum core modules
-  - `@app`: server-side application services for manual routes only
-  - `@generated/*`: generated app surfaces
-
-## Design Rules
-
-- Prefer explicit `server/index.ts` bootstrap over hidden registration.
-- Prefer controller-backed app APIs over ad hoc manual `/api/...` routes.
-- Prefer service classes over server helpers with hidden dependencies.
-- Keep one canonical source of truth for catalogs, registries, and shared types.
-- Reuse project-local Shadcn-based UI primitives when the app already provides them.
-- Before inventing a helper, primitive, parser, formatter, SDK wrapper, or build-time tool, first check whether the repo already depends on a suitable package.
-- If it does not, search npm before writing a custom implementation.
-- Prefer widely adopted, actively maintained, flexible, well-typed packages.
-- Only build custom infrastructure when packages would clearly hurt bundle size, SSR behavior, performance, explicit contracts, or long-term maintainability.
-- If you choose custom over a package, state briefly why.
-
-## Discouraged Patterns
-
-- `api.fetch(...)` inside page files for SSR loading
-- client-side `@app` imports
-- runtime `@models` imports
-- request-scoped state inside normal service methods
-- hiding route registration behind abstractions that remove the top-level `Router.page(...)` call
-- editing `.proteum` directly
-
-## Verification
-
-Verify at the correct layer:
-
-- route additions: boot the app and hit the real URL
-- controller changes: exercise the generated client call or generated `/api/...` endpoint
-- SSR changes: load the real page and inspect rendered HTML plus browser console
-- router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app
-
-When an app may already be running, check the default port from `PORT` or `./.proteum/manifest.json` and inspect `proteum trace requests`, `proteum trace latest`, and `proteum trace show <requestId>` before reproducing the issue. If those traces are not enough, arm `npx proteum trace arm --capture deep`, reproduce once, then inspect the new request.
-
-Useful commands: `npx proteum init <dir> --name <name>`, `npx proteum create <kind> <target>`, `proteum dev`, `npx proteum refresh`, `npx proteum typecheck`, `npx proteum lint`, `npx proteum check`, `npx proteum build prod`, `npx proteum command <path>`.

package/server/services/auth/router/service.json

@@ -1,6 +0,0 @@
-{
-    "id": "Core/Users/Router",
-    "name": "RouteUser",
-    "parent": "router",
-    "dependences": []
-}

package/server/services/auth/service.json

@@ -1,6 +0,0 @@
-{
-    "id": "Core/Users",
-    "name": "Users",
-    "parent": "app",
-    "dependences": []
-}

package/server/services/cron/service.json

@@ -1,6 +0,0 @@
-{
-    "id": "Core/Cron",
-    "name": "Cron",
-    "parent": "app",
-    "dependences": []
-}

package/server/services/disks/drivers/local/service.json

@@ -1,6 +0,0 @@
-{
-    "id": "Core/Disks/Local",
-    "name": "LocalDiskDriver",
-    "parent": "disks",
-    "dependences": []
-}

package/server/services/disks/drivers/s3/service.json

@@ -1,6 +0,0 @@
-{
-    "id": "Core/Disks/S3",
-    "name": "S3DiskDriver",
-    "parent": "disks",
-    "dependences": []
-}

package/server/services/disks/service.json

@@ -1,6 +0,0 @@
-{
-    "id": "Core/Disks",
-    "name": "Disks",
-    "parent": "app",
-    "dependences": []
-}

package/server/services/fetch/service.json

@@ -1,7 +0,0 @@
-{
-    "id": "Core/Fetch",
-    "name": "Fetch",
-    "parent": "app",
-    "dependences": [],
-    "priority": 0
-}

package/server/services/prisma/service.json

@@ -1,6 +0,0 @@
-{
-    "id": "Core/Models",
-    "name": "Models",
-    "parent": "app",
-    "dependences": []
-}

package/server/services/router/service.json

@@ -1,6 +0,0 @@
-{
-    "id": "Core/Router",
-    "name": "Router",
-    "parent": "app",
-    "dependences": []
-}

package/server/services/schema/router/service.json

@@ -1,6 +0,0 @@
-{
-    "id": "Core/Schema/Router",
-    "name": "RouteSchema",
-    "parent": "router",
-    "dependences": []
-}

package/server/services/schema/service.json

@@ -1,6 +0,0 @@
-{
-    "id": "Core/Schema",
-    "name": "Schema",
-    "parent": "app",
-    "dependences": []
-}

package/server/services/security/encrypt/aes/service.json

@@ -1,6 +0,0 @@
-{
-    "id": "Core/Encryption/AES",
-    "name": "AES",
-    "parent": "app",
-    "dependences": []
-}