proteum 2.1.0-5 → 2.1.1

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

@@ -21,8 +21,11 @@ import * as csp from 'express-csp-header';
 
 // Core
 import Container from '@server/app/container';
+import type CronManager from '@server/services/cron';
+import type CronTask from '@server/services/cron/CronTask';
 import type { TServerRouter } from '..';
 import { serverHotReloadMessageType } from '@common/dev/serverHotReload';
+import { explainSectionNames } from '@common/dev/diagnostics';
 
 // Middlewaees (core)
 import { isMutipart, MiddlewareFormData } from './multipart';
@@ -230,41 +233,149 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
     }
 
     private registerDevTraceRoutes(routes: express.Express) {
-        if (!this.app.container.Trace.isEnabled()) return;
+        if (!__DEV__ || this.app.env.profile !== 'dev') return;
+
+        if (this.app.container.Trace.isEnabled()) {
+            routes.get('/__proteum/trace/requests', (req, res) => {
+                const rawLimit = Array.isArray(req.query.limit) ? req.query.limit[0] : req.query.limit;
+                const parsedLimit = typeof rawLimit === 'string' ? Number.parseInt(rawLimit, 10) : NaN;
+                const limit = Number.isFinite(parsedLimit) && parsedLimit > 0 ? parsedLimit : 20;
+
+                res.json({ requests: this.app.container.Trace.listRequests(limit) });
+            });
+
+            routes.get('/__proteum/trace/latest', (_req, res) => {
+                const request = this.app.container.Trace.getLatestRequest();
+                if (!request) {
+                    res.status(404).json({ error: 'No request trace is available yet.' });
+                    return;
+                }
+
+                res.json({ request });
+            });
+
+            routes.get('/__proteum/trace/requests/:id', (req, res) => {
+                const request = this.app.container.Trace.getRequest(req.params.id);
+                if (!request) {
+                    res.status(404).json({ error: `Trace ${req.params.id} was not found.` });
+                    return;
+                }
+
+                res.json({ request });
+            });
+
+            routes.post('/__proteum/trace/arm', (req, res) => {
+                const rawCapture = typeof req.body.capture === 'string' ? req.body.capture : 'deep';
+                const capture = this.app.container.Trace.armNextRequest(rawCapture);
+
+                res.json({ armed: true, capture });
+            });
+        }
+
+        routes.get('/__proteum/explain', (req, res) => {
+            const rawSections = [
+                ...(Array.isArray(req.query.section) ? req.query.section : req.query.section ? [req.query.section] : []),
+                ...(Array.isArray(req.query.sections)
+                    ? req.query.sections.flatMap((value) => (typeof value === 'string' ? value.split(',') : []))
+                    : typeof req.query.sections === 'string'
+                      ? req.query.sections.split(',')
+                      : []),
+            ]
+                .map((value) => (typeof value === 'string' ? value.trim() : ''))
+                .filter(Boolean);
+
+            try {
+                const diagnostics = this.app.getDevDiagnostics();
+                const sections = diagnostics.normalizeExplainSections(rawSections);
+                res.json(diagnostics.explain(sections));
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const isBadRequest = explainSectionNames.some((sectionName) => message.includes(sectionName)) || message.includes('Unknown explain section');
+                res.status(isBadRequest ? 400 : 500).json({ error: message });
+            }
+        });
+
+        routes.get('/__proteum/doctor', (req, res) => {
+            const rawStrict = Array.isArray(req.query.strict) ? req.query.strict[0] : req.query.strict;
+            const strict = rawStrict === '1' || rawStrict === 'true';
 
-        routes.get('/__proteum/trace/requests', (req, res) => {
-            const rawLimit = Array.isArray(req.query.limit) ? req.query.limit[0] : req.query.limit;
-            const parsedLimit = typeof rawLimit === 'string' ? Number.parseInt(rawLimit, 10) : NaN;
-            const limit = Number.isFinite(parsedLimit) && parsedLimit > 0 ? parsedLimit : 20;
+            try {
+                res.json(this.app.getDevDiagnostics().doctor(strict));
+            } catch (error) {
+                res.status(500).json({ error: error instanceof Error ? error.message : String(error) });
+            }
+        });
 
-            res.json({ requests: this.app.container.Trace.listRequests(limit) });
+        routes.get('/__proteum/cron/tasks', (_req, res) => {
+            const cron = this.getCronManager();
+            res.json({
+                automaticExecution: cron?.isAutomaticExecutionEnabled() ?? false,
+                tasks: cron?.listTasks() ?? [],
+            });
         });
 
-        routes.get('/__proteum/trace/latest', (_req, res) => {
-            const request = this.app.container.Trace.getLatestRequest();
-            if (!request) {
-                res.status(404).json({ error: 'No request trace is available yet.' });
+        routes.get('/__proteum/commands', (_req, res) => {
+            res.json({ commands: this.app.getDevCommands().list() });
+        });
+
+        routes.post('/__proteum/commands/run', async (req, res) => {
+            const commandPath = typeof req.body?.path === 'string' ? req.body.path.trim() : '';
+            if (!commandPath) {
+                res.status(400).json({ error: 'Command path is required.' });
                 return;
             }
 
-            res.json({ request });
+            try {
+                const execution = await this.app.getDevCommands().run(commandPath);
+                res.json({ execution });
+            } catch (error) {
+                const execution =
+                    error instanceof Error && 'execution' in error && typeof error.execution === 'object'
+                        ? error.execution
+                        : undefined;
+                const statusCode = error instanceof Error && error.name === 'NotFound' ? 404 : 500;
+
+                res.status(statusCode).json({
+                    error: error instanceof Error ? error.message : String(error),
+                    execution,
+                });
+            }
         });
 
-        routes.get('/__proteum/trace/requests/:id', (req, res) => {
-            const request = this.app.container.Trace.getRequest(req.params.id);
-            if (!request) {
-                res.status(404).json({ error: `Trace ${req.params.id} was not found.` });
+        routes.post('/__proteum/cron/tasks/run', async (req, res) => {
+            const cron = this.getCronManager();
+            if (!cron) {
+                res.status(404).json({ error: 'Cron service is not registered for this app.' });
                 return;
             }
 
-            res.json({ request });
-        });
+            const name = typeof req.body?.name === 'string' ? req.body.name.trim() : '';
+            if (!name) {
+                res.status(400).json({ error: 'Cron task name is required.' });
+                return;
+            }
 
-        routes.post('/__proteum/trace/arm', (req, res) => {
-            const rawCapture = typeof req.body.capture === 'string' ? req.body.capture : 'deep';
-            const capture = this.app.container.Trace.armNextRequest(rawCapture);
+            let task: CronTask;
+            try {
+                task = cron.get(name);
+            } catch (error) {
+                res.status(404).json({ error: error instanceof Error ? error.message : String(error) });
+                return;
+            }
 
-            res.json({ armed: true, capture });
+            try {
+                await cron.exec(name);
+                res.json({ task: task.toProfilerTask() });
+            } catch (error) {
+                res.status(500).json({
+                    error: error instanceof Error ? error.message : String(error),
+                    task: task.toProfilerTask(),
+                });
+            }
         });
     }
+
+    private getCronManager() {
+        return (this.app as typeof this.app & { Cron?: CronManager }).Cron;
+    }
 }

package/server/services/router/index.ts

@@ -36,6 +36,12 @@ import BaseRouter, {
 import type { TSsrUnresolvedRoute, TRegisterPageArgs } from '@common/router/contracts';
 import { buildRegex, getRegisterPageArgs } from '@common/router/register';
 import { layoutsList, getLayout } from '@common/router/layouts';
+import {
+    profilerOriginHeader,
+    profilerParentRequestIdHeader,
+    profilerSessionIdHeader,
+    profilerTraceRequestIdHeader,
+} from '@common/dev/profiler';
 import { TFetcherList } from '@common/router/request/api';
 import type { TFrontRenderer } from '@common/router/response/page';
 
@@ -587,7 +593,11 @@ export default class ServerRouter<
             url: request.url,
             headers: request.headers,
             data: request.data,
+            profilerSessionId: request.headers[profilerSessionIdHeader] || undefined,
+            profilerOrigin: request.headers[profilerOriginHeader] || undefined,
+            profilerParentRequestId: request.headers[profilerParentRequestIdHeader] || undefined,
         });
+        if (this.app.container.Trace.isEnabled()) res.setHeader(profilerTraceRequestIdHeader, request.id);
 
         let response: ServerResponse<this>;
         try {
@@ -899,10 +909,36 @@ export default class ServerRouter<
             if (!fetcher || !('method' in fetcher)) continue;
 
             const { method, path, data } = fetcher;
+            const callId = this.app.container.Trace.startCall(request.id, {
+                origin: 'api-batch-fetcher',
+                label: id,
+                method,
+                path,
+                fetcherId: id,
+                requestDataKeys: data && typeof data === 'object' ? Object.keys(data) : [],
+                requestData: data,
+            });
 
-            const response = await this.resolve(request.children(method, path, data));
-
-            responseData[id] = response.data;
+            try {
+                const response = await this.resolve(request.children(method, path, data));
+                responseData[id] = response.data;
+                this.app.container.Trace.finishCall(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,
+                });
+            } catch (error) {
+                const typedError = error instanceof Error ? error : new Error(typeof error === 'string' ? error : 'Unknown error');
+                const statusCode = 'http' in typedError ? Number((typedError as Error & { http?: number }).http) : undefined;
+                this.app.container.Trace.finishCall(request.id, callId, {
+                    statusCode: Number.isFinite(statusCode) ? statusCode : undefined,
+                    errorMessage: typedError.message,
+                });
+                throw error;
+            }
 
             // TODO: merge response.headers ?
         }
@@ -929,7 +965,7 @@ export default class ServerRouter<
             'error',
             {
                 code,
-                error: error instanceof Error ? error : new Error(error.message),
+                error,
             },
             'summary',
         );

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

@@ -80,7 +80,36 @@ export default class ApiClientRequest extends RequestService implements ApiClien
 
             // Create a children request to resolve the api data
             const request = this.request.children(method, path, data);
-            fetchedData[id] = await request.router.resolve(request).then((res) => res.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,
+            });
+
+            try {
+                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,
+                });
+            } catch (error) {
+                const typedError = error instanceof Error ? error : new Error(typeof error === 'string' ? error : 'Unknown error');
+                const statusCode = 'http' in typedError ? Number((typedError as Error & { http?: number }).http) : undefined;
+                this.request.router.app.container.Trace.finishCall(this.request.id, callId, {
+                    statusCode: Number.isFinite(statusCode) ? statusCode : undefined,
+                    errorMessage: typedError.message,
+                });
+                throw error;
+            }
         }
 
         return fetchedData;

package/skills/clean-project-code/SKILL.md

@@ -32,10 +32,13 @@ Use fast search tools such as `rg` to verify references. Check exports, dynamic
 5. Keep uncertain cases.
 If code looks unused but safety is not clear, keep it and report it separately. Favor false negatives over unsafe deletions.
 
-6. Apply style only on touched files.
+6. Audit redundancy candidates across the project.
+List catalogs, constants, and functions that look redundant and could be centralized, unified, or merged. Treat this as a reporting task by default unless the user explicitly asked for structural refactoring. Give each candidate an impact score from 1 to 5, where 5 is the highest expected payoff for maintainability, consistency, or simplification.
+
+7. Apply style only on touched files.
 Follow the repository coding style for files you change. Run Prettier with the repo config, preferably on touched files only unless the user explicitly asks for repo-wide formatting.
 
-7. Verify.
+8. Verify.
 Run the smallest relevant verification available after edits. Prefer project-native checks. If no suitable automated verification exists, say so explicitly.
 
 ## Deletion Rules
@@ -50,6 +53,7 @@ Run the smallest relevant verification available after edits. Prefer project-nat
 Always report:
 - what was removed
 - what was intentionally left unchanged because it was uncertain
+- which catalogs, constants, and functions appear redundant across the project, with a proposed centralization or merge direction and an impact score from 1 to 5
 - what verification was run
 - what could not be verified automatically
 
@@ -59,5 +63,6 @@ When the user provides a cleanup brief, turn it into an execution checklist befo
 - instructions read
 - safe deletion targets identified
 - risky candidates deferred
+- redundancy candidates and impact scoring captured
 - formatting scope confirmed
 - verification plan chosen

package/test-results/.last-run.json

@@ -0,0 +1,4 @@
+{
+  "status": "failed",
+  "failedTests": []
+}

package/types/aliases.d.ts

@@ -18,6 +18,12 @@ declare module '@/server' {
     export = InstanceType<ServerApplicationClass>;
 }
 
+declare module '@/server/index' {
+    import ServerApplicationBase from '../server/app';
+
+    export default class ServerApplication extends ServerApplicationBase {}
+}
+
 declare module '@/client' {
     const ClientApplicationClass: import('../client/app').default;
     export = InstanceType<ClientApplicationClass>;