proteum 2.4.1 → 2.4.3

package/cli/runtime/commands.ts

@@ -695,6 +695,38 @@ class PerfCommand extends ProteumCommand {
     }
 }
 
+class DbCommand extends ProteumCommand {
+    public static paths = [['db']];
+
+    public static usage = buildUsage('db');
+
+    public port = Option.String('--port', { description: 'Target an existing dev server on the given port.' });
+    public url = Option.String('--url', { description: 'Target an existing dev server at the given base URL.' });
+    public limit = Option.String('--limit', { description: 'Maximum number of result rows to return, up to 500.' });
+    public timeout = Option.String('--timeout', { description: 'Database query timeout in milliseconds, up to 30000.' });
+    public json = Option.Boolean('--json', false, { description: 'Compatibility flag; compact JSON is the default output.' });
+    public full = Option.Boolean('--full', false, { description: 'Print the full database query payload.' });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [first = '', ...restArgs] = this.args;
+        const sql = first === 'query' ? restArgs.join(' ').trim() : [first, ...restArgs].join(' ').trim();
+
+        this.setCliArgs({
+            action: 'query',
+            full: this.full,
+            json: this.json,
+            limit: this.limit ?? '',
+            port: this.port ?? '',
+            sql,
+            timeout: this.timeout ?? '',
+            url: this.url ?? '',
+        });
+
+        await runCommandModule(() => import('../commands/db'));
+    }
+}
+
 class RuntimeCommand extends ProteumCommand {
     public static paths = [['runtime']];
 
@@ -859,6 +891,7 @@ export const registeredCommands = {
     orient: OrientCommand,
     diagnose: DiagnoseCommand,
     perf: PerfCommand,
+    db: DbCommand,
     runtime: RuntimeCommand,
     mcp: McpCommand,
     trace: TraceCommand,
@@ -894,6 +927,7 @@ export const createCli = (version: string) => {
     clipanion.register(OrientCommand);
     clipanion.register(DiagnoseCommand);
     clipanion.register(PerfCommand);
+    clipanion.register(DbCommand);
     clipanion.register(RuntimeCommand);
     clipanion.register(McpCommand);
     clipanion.register(TraceCommand);

package/cli/utils/agents.ts

@@ -612,16 +612,17 @@ function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoR
         '',
         '1. When a Proteum MCP client is available, call MCP `workflow_start` first. Pass `cwd` when `projectId` is not known, or pass the stable `projectId` from `projects_list` when it is known.',
         '2. Use the `projectId` returned by live `workflow_start` for every follow-up app-bound MCP tool. If `workflow_start` is ambiguous or returns offline candidates, call MCP `project_resolve { cwd }`, select the intended app root, follow its port-inspected next action when needed, then retry `workflow_start`.',
-        '3. After `projectId` is selected, use MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, and `logs_tail` for read-only runtime, owner, instruction, route, trace, perf, and log reads.',
+        '3. After `projectId` is selected, use MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, `logs_tail`, and `db_query` for read-only runtime, owner, instruction, route, trace, perf, log, and database reads.',
         '4. Do not run CLI equivalents after a successful MCP result for the same read. Do not run broad source searches for route/page/controller ownership after `workflow_start`, `orient`, or `explain_summary` already returned the owner.',
         '5. Treat selected instruction previews returned by MCP as the instruction source for read-only discovery and diagnostics. Read full files only before edits or git writes, when the returned `fullRead`/`fullReadPolicy` requires it, or when the preview is insufficient.',
         '6. Use `npx proteum runtime status` before starting a dev server only when MCP runtime status is unavailable, so an existing tracked session can be reused and the configured router/HMR ports can be checked without probing page bodies. If it says health is unreachable, do not run `diagnose`, `trace`, or `perf`; stop/repair/start the dev session first.',
         '7. During `npx proteum dev`, Proteum ensures one managed machine MCP daemon is running and routes app-bound reads to the read-only runtime endpoint at `/__proteum/mcp` instead of spawning equivalent CLI diagnostics.',
-        '8. If machine MCP routing fails, run `npx proteum mcp status` and `npx proteum runtime status`; if no live session exists, use the exact next action from MCP offline routing or runtime status instead of assuming the manifest default port. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server.',
-        '9. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not start a second dev server in the same worktree or a second managed MCP daemon. Then retry MCP `workflow_start`.',
-        '10. Use MCP `diagnose { projectId, path }` for request-time issues before raw trace, perf, browser, or broad source search; use `npx proteum diagnose <target>` only as fallback or final terminal evidence.',
-        '11. Use `route_candidates`, `explain_summary`, or `npx proteum explain owner <query>` to pick routes. Do not run `npx proteum explain --routes --full` unless compact route/owner tools explicitly cannot answer the raw route-array question.',
-        '12. Use `--full`, `--manifest`, `--events`, or MCP `detail: "full"` only when compact output says the omitted detail is needed.',
+        '8. Terminal `npx proteum mcp` prints a compact central MCP ready banner with the HTTP client URL when it starts or reuses the managed daemon.',
+        '9. If machine MCP routing fails, run `npx proteum mcp status` and `npx proteum runtime status`; if no live session exists, use the exact next action from MCP offline routing or runtime status instead of assuming the manifest default port. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server.',
+        '10. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not start a second dev server in the same worktree or a second managed MCP daemon. Then retry MCP `workflow_start`.',
+        '11. Use MCP `diagnose { projectId, path }` for request-time issues before raw trace, perf, browser, or broad source search; use `npx proteum diagnose <target>` only as fallback or final terminal evidence.',
+        '12. Use `route_candidates`, `explain_summary`, or `npx proteum explain owner <query>` to pick routes. Do not run `npx proteum explain --routes --full` unless compact route/owner tools explicitly cannot answer the raw route-array question.',
+        '13. Use `--full`, `--manifest`, `--events`, or MCP `detail: "full"` only when compact output says the omitted detail is needed.',
         '',
         'CLI remains the reproducible surface for `dev`, `build`, `check`, `verify`, migrations, and final command evidence. MCP remains read-only and returns compact `proteum-mcp-v1` JSON.',
         '',
@@ -631,6 +632,7 @@ function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoR
         '- Never edit generated files under `.proteum`.',
         '- Never create or edit Prisma migration files manually.',
         '- Never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, `DROP TABLE`, or `CREATE INDEX`.',
+        '- For read-only SQL diagnosis, use MCP `db_query` or `npx proteum db query "<sql>"`; only one capped `SELECT`, `SHOW`, or `EXPLAIN` statement is allowed.',
         '- If `schema.prisma` changes, ask the user to run `npx prisma migrate dev --config ./prisma.config.ts --name <migration name>` and wait for `continue` before validation.',
         '- For production changes, add or update focused unit tests for touched behavior when applicable, targeting 100% meaningful coverage for changed production paths.',
         '- Do not run `git restore` or `git reset`.',
@@ -649,6 +651,7 @@ function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoR
         '## Routing Table',
         '',
         '- Non-trivial coding tasks, feature docs, product intent, acceptance criteria, or docs updates: read `DOCUMENTATION.md`.',
+        '- GEO/SEO/crawler/structured-data/AI-source changes: read `DOCUMENTATION.md`, `CODING_STYLE.md`, `tests/AGENTS.md`, and update or create a docs page under `docs/` describing the public contract, routes, validation, and operational caveats.',
         '- Raw errors, failing requests, traces, perf, or reproduction: read `diagnostics.md`.',
         '- Implementation edits: read `CODING_STYLE.md` before editing.',
         '- Client files or pages: read `client/AGENTS.md`; for page route/data/render work also read `client/pages/AGENTS.md`.',

package/common/dev/database.ts

@@ -0,0 +1,229 @@
+export type TDatabaseReadQueryKind = 'explain' | 'select' | 'show';
+
+export type TDatabaseReadQueryInput = {
+    limit?: number;
+    sql: string;
+    timeoutMs?: number;
+};
+
+export type TDatabaseReadQueryColumn = {
+    name: string;
+    table?: string;
+    type?: number | string;
+};
+
+export type TDatabaseReadQueryValue = boolean | number | string | null;
+
+export type TDatabaseReadQueryRow = Record<string, TDatabaseReadQueryValue>;
+
+export type TDatabaseReadQueryResponse = {
+    columns: TDatabaseReadQueryColumn[];
+    elapsedMs: number;
+    kind: TDatabaseReadQueryKind;
+    limit: number;
+    limited: boolean;
+    rowCount: number;
+    rows: TDatabaseReadQueryRow[];
+    sql: string;
+};
+
+export type TValidatedDatabaseReadQuery = {
+    kind: TDatabaseReadQueryKind;
+    sql: string;
+};
+
+export const defaultDatabaseReadLimit = 50;
+export const maxDatabaseReadLimit = 500;
+export const defaultDatabaseReadTimeoutMs = 5_000;
+export const maxDatabaseReadTimeoutMs = 30_000;
+
+const allowedQueryKinds = new Set<TDatabaseReadQueryKind>(['explain', 'select', 'show']);
+const sqlKeywordPattern = /^[A-Za-z]+/;
+const sqlCommentPattern = /\/\*[\s\S]*?\*\//g;
+const sqlLineCommentPattern = /(?:^|\n)\s*(?:--|#).*?(?=\n|$)/g;
+
+const clampInteger = ({ fallback, max, min, value }: { fallback: number; max: number; min: number; value?: number }) => {
+    if (value === undefined || !Number.isInteger(value) || value < min) return fallback;
+
+    return Math.min(value, max);
+};
+
+export const normalizeDatabaseReadLimit = (limit?: number) =>
+    clampInteger({
+        fallback: defaultDatabaseReadLimit,
+        max: maxDatabaseReadLimit,
+        min: 1,
+        value: limit,
+    });
+
+export const normalizeDatabaseReadTimeoutMs = (timeoutMs?: number) =>
+    clampInteger({
+        fallback: defaultDatabaseReadTimeoutMs,
+        max: maxDatabaseReadTimeoutMs,
+        min: 100,
+        value: timeoutMs,
+    });
+
+const skipLeadingTrivia = (sql: string) => {
+    let index = 0;
+
+    while (index < sql.length) {
+        const char = sql[index];
+        const next = sql[index + 1];
+
+        if (/\s/.test(char)) {
+            index += 1;
+            continue;
+        }
+
+        if (char === '-' && next === '-') {
+            index = sql.indexOf('\n', index + 2);
+            if (index === -1) return sql.length;
+            continue;
+        }
+
+        if (char === '#') {
+            index = sql.indexOf('\n', index + 1);
+            if (index === -1) return sql.length;
+            continue;
+        }
+
+        if (char === '/' && next === '*') {
+            const end = sql.indexOf('*/', index + 2);
+            if (end === -1) throw new Error('SQL contains an unterminated block comment.');
+            index = end + 2;
+            continue;
+        }
+
+        return index;
+    }
+
+    return index;
+};
+
+const stripSqlComments = (sql: string) =>
+    sql.replace(sqlCommentPattern, ' ').replace(sqlLineCommentPattern, '\n');
+
+const findFirstStatementEnd = (sql: string) => {
+    let quote: "'" | '"' | '`' | undefined;
+    let lineComment = false;
+    let blockComment = false;
+
+    for (let index = 0; index < sql.length; index += 1) {
+        const char = sql[index];
+        const next = sql[index + 1];
+
+        if (lineComment) {
+            if (char === '\n') lineComment = false;
+            continue;
+        }
+
+        if (blockComment) {
+            if (char === '*' && next === '/') {
+                blockComment = false;
+                index += 1;
+            }
+            continue;
+        }
+
+        if (quote) {
+            if (char === '\\') {
+                index += 1;
+                continue;
+            }
+            if (char === quote) quote = undefined;
+            continue;
+        }
+
+        if (char === '-' && next === '-') {
+            lineComment = true;
+            index += 1;
+            continue;
+        }
+
+        if (char === '#') {
+            lineComment = true;
+            continue;
+        }
+
+        if (char === '/' && next === '*') {
+            blockComment = true;
+            index += 1;
+            continue;
+        }
+
+        if (char === '\'' || char === '"' || char === '`') {
+            quote = char;
+            continue;
+        }
+
+        if (char === ';') return index;
+    }
+
+    if (quote) throw new Error('SQL contains an unterminated quoted string.');
+    if (blockComment) throw new Error('SQL contains an unterminated block comment.');
+
+    return -1;
+};
+
+const assertSingleStatement = (sql: string) => {
+    const end = findFirstStatementEnd(sql);
+    if (end === -1) return sql.trim();
+
+    const first = sql.slice(0, end).trim();
+    const rest = stripSqlComments(sql.slice(end + 1)).trim();
+    if (rest) throw new Error('Only one read-only SQL statement may be executed.');
+
+    return first;
+};
+
+const getReadQueryKind = (sql: string): TDatabaseReadQueryKind => {
+    const start = skipLeadingTrivia(sql);
+    const keyword = sql.slice(start).match(sqlKeywordPattern)?.[0]?.toLowerCase();
+
+    if (!keyword || !allowedQueryKinds.has(keyword as TDatabaseReadQueryKind)) {
+        throw new Error('Only SELECT, SHOW, and EXPLAIN SQL statements are allowed.');
+    }
+
+    return keyword as TDatabaseReadQueryKind;
+};
+
+const assertAllowedReadQueryShape = (sql: string) => {
+    const normalized = stripSqlComments(sql).replace(/\s+/g, ' ').trim().toLowerCase();
+
+    if (/\bexplain\s+analyze\b/.test(normalized)) {
+        throw new Error('EXPLAIN ANALYZE is not allowed because it executes the target query.');
+    }
+
+    if (/\binto\s+(?:out|dump)file\b/.test(normalized)) {
+        throw new Error('SELECT INTO OUTFILE and SELECT INTO DUMPFILE are not allowed.');
+    }
+
+    if (/\b(?:load_file|pg_read_file|pg_read_binary_file|pg_ls_dir)\s*\(/.test(normalized)) {
+        throw new Error('Database file-read functions are not allowed in database diagnostics.');
+    }
+
+    if (
+        /\bfor\s+(?:update|no\s+key\s+update|share|key\s+share)\b/.test(normalized) ||
+        /\block\s+in\s+share\s+mode\b/.test(normalized)
+    ) {
+        throw new Error('Locking read statements are not allowed in database diagnostics.');
+    }
+
+    if (/\b(?:sleep|benchmark|pg_sleep|pg_sleep_for|pg_sleep_until)\s*\(/.test(normalized)) {
+        throw new Error('Sleep and benchmark functions are not allowed in database diagnostics.');
+    }
+};
+
+export const validateDatabaseReadQuery = (rawSql: string): TValidatedDatabaseReadQuery => {
+    const normalizedSql = rawSql.replace(/^\uFEFF/, '').trim();
+    if (!normalizedSql) throw new Error('SQL query is required.');
+    if (normalizedSql.length > 20_000) throw new Error('SQL query is too long for database diagnostics.');
+
+    const sql = assertSingleStatement(normalizedSql);
+    const kind = getReadQueryKind(sql);
+
+    assertAllowedReadQueryShape(sql);
+
+    return { kind, sql };
+};

package/common/dev/mcpPayloads.ts

@@ -1,4 +1,5 @@
 import type { TDevConsoleLogLevel, TDevConsoleLogsResponse } from './console';
+import type { TDatabaseReadQueryResponse } from './database';
 import type { TDoctorResponse } from './diagnostics';
 import { buildExplainSummaryItems } from './diagnostics';
 import { explainOwner, type TDiagnoseResponse, type TExplainOwnerResponse, type TOrientResponse } from './inspection';
@@ -733,6 +734,30 @@ export const compactLogsResponse = ({
                 : undefined,
     });
 
+export const compactDatabaseReadQueryResponse = (response: TDatabaseReadQueryResponse) =>
+    createMcpPayload({
+        summary: `${response.kind.toUpperCase()} returned ${response.rows.length}/${response.rowCount} rows in ${response.elapsedMs} ms${response.limited ? ` (limited to ${response.limit})` : ''}.`,
+        data: {
+            kind: response.kind,
+            elapsedMs: response.elapsedMs,
+            rowCount: response.rowCount,
+            returnedRowCount: response.rows.length,
+            limit: response.limit,
+            limited: response.limited,
+            columns: response.columns,
+            rows: response.rows,
+        },
+        omitted: response.limited
+            ? [
+                  {
+                      reason: `Rows are capped at ${response.limit}. Raise the limit up to 500 or make the read query narrower if more detail is needed.`,
+                      tool: 'db_query',
+                      toolArgs: { sql: response.sql, limit: Math.min(response.limit * 2, 500) },
+                  },
+              ]
+            : undefined,
+    });
+
 const readPreview = (filepath: string) => {
     if (fs === undefined) return undefined;
     try {

package/common/dev/mcpServer.ts

@@ -7,6 +7,7 @@ import { stringifyMcpPayload, type TProteumMcpPayload } from './mcpPayloads';
 export type TProteumMcpDetail = 'compact' | 'full';
 
 export type TProteumMcpProvider = {
+    dbQuery: (input: { limit?: number; sql: string; timeoutMs?: number }) => Promise<TProteumMcpPayload>;
     diagnose: (input: {
         logsLevel?: 'silly' | 'log' | 'info' | 'warn' | 'error';
         logsLimit?: number;
@@ -64,6 +65,8 @@ const detailSchema = z.enum(['compact', 'full']).optional();
 const logsLevelSchema = z.enum(['silly', 'log', 'info', 'warn', 'error']).optional();
 const positiveLimitSchema = z.number().int().min(1).max(100).optional();
 const offsetSchema = z.number().int().min(0).max(10_000).optional();
+const databaseLimitSchema = z.number().int().min(1).max(500).optional();
+const databaseTimeoutSchema = z.number().int().min(100).max(30_000).optional();
 
 export const createProteumMcpServer = ({ provider, version }: TCreateProteumMcpServerArgs) => {
     const server = new McpServer(
@@ -264,6 +267,21 @@ export const createProteumMcpServer = ({ provider, version }: TCreateProteumMcpS
         async ({ level, limit }) => jsonToolResult(await provider.logsTail({ level, limit })),
     );
 
+    server.registerTool(
+        'db_query',
+        {
+            annotations: readOnlyAnnotations,
+            description: 'Run one capped read-only database diagnostic query. Only SELECT, SHOW, and EXPLAIN are allowed.',
+            inputSchema: {
+                limit: databaseLimitSchema,
+                sql: z.string().min(1).describe('One SELECT, SHOW, or EXPLAIN SQL statement.'),
+                timeoutMs: databaseTimeoutSchema,
+            },
+            title: 'Proteum Database Query',
+        },
+        async ({ limit, sql, timeoutMs }) => jsonToolResult(await provider.dbQuery({ limit, sql, timeoutMs })),
+    );
+
     for (const [name, uri, description] of [
         ['runtime-status', 'proteum://runtime/status', 'Current compact runtime status.'],
         ['instructions-router', 'proteum://instructions/router', 'Current instruction routing contract.'],

package/docs/agent-routing.md

@@ -66,7 +66,7 @@ Use MCP for repeated reads when a client is available:
 proteum mcp
 ```
 
-The machine router discovers live `proteum dev` sessions and offline Proteum app roots under a cwd. `proteum dev` ensures one managed machine MCP daemon is running; terminal `proteum mcp` starts or reuses that daemon, while MCP clients can use stdio. Agents should call MCP `workflow_start` with `cwd` or a known `projectId`, use `project_resolve { cwd }` when routing is ambiguous or offline, and pass the returned live `projectId` to every follow-up app-bound MCP tool. Offline candidates include port-inspected next actions, so agents should follow those instead of guessing the manifest default port. The router forwards to the selected dev-hosted `/__proteum/mcp` endpoint and strips routing fields before the app sees the call.
+The machine router discovers live `proteum dev` sessions and offline Proteum app roots under a cwd. `proteum dev` ensures one managed machine MCP daemon is running; terminal `proteum mcp` starts or reuses that daemon and prints a compact central MCP banner with the HTTP client URL, while MCP clients can use stdio. Agents should call MCP `workflow_start` with `cwd` or a known `projectId`, use `project_resolve { cwd }` when routing is ambiguous or offline, and pass the returned live `projectId` to every follow-up app-bound MCP tool. Offline candidates include port-inspected next actions, so agents should follow those instead of guessing the manifest default port. The router forwards to the selected dev-hosted `/__proteum/mcp` endpoint and strips routing fields before the app sees the call.
 
 If machine MCP routing returns offline candidates, choose the intended app root and follow that candidate's next action from the app root, not from the monorepo wrapper. If machine MCP routing fails, run `proteum mcp status` and `proteum runtime status` from the intended app root; if no live session exists, use the exact Start Dev next action from runtime status so occupied router/HMR ports are avoided. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. Do not `curl` normal page routes to identify which app owns a port; use runtime status or Proteum dev-only endpoints. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Do not start a second dev server in the same worktree, and do not start a second managed MCP daemon. Then retry MCP `workflow_start`.
 

package/docs/mcp.md

@@ -15,7 +15,7 @@ Start the router from any directory:
 proteum mcp
 ```
 
-When run from a terminal, `proteum mcp` starts or reuses the managed local daemon at `http://127.0.0.1:3769/mcp`. When an MCP client launches it over pipes, use stdio:
+When run from a terminal, `proteum mcp` starts or reuses the managed local daemon at `http://127.0.0.1:3769/mcp`. The terminal output prints a compact `CENTRAL MCP READY` banner with the one-line client setup instruction, `Connect MCP client (HTTP): <mcp-url>`. When an MCP client launches it over pipes, use stdio:
 
 ```bash
 proteum mcp --stdio
@@ -44,6 +44,7 @@ Example tool calls:
 {"tool":"route_candidates","arguments":{"projectId":"prj_0123abcd4567","query":"dashboard","limit":8}}
 {"tool":"explain_summary","arguments":{"projectId":"prj_0123abcd4567","query":"/dashboard"}}
 {"tool":"diagnose","arguments":{"projectId":"prj_0123abcd4567","path":"/dashboard"}}
+{"tool":"db_query","arguments":{"projectId":"prj_0123abcd4567","sql":"SELECT id, email FROM User LIMIT 5","limit":5}}
 ```
 
 `workflow_start` is the only app-bound bootstrap tool that may resolve from `cwd` when `projectId` is not known. It may return offline app candidates when no matching dev server is running yet. Other app-bound tools require a live `projectId`; if they omit it, the router returns a compact error that tells the agent to call `projects_list` or `project_resolve`. There is no single-project fallback, because wrong-project reads are worse than an explicit routing retry.
@@ -131,6 +132,7 @@ App-bound tools require `projectId` when called through `proteum mcp`:
 | `perf_top` | Hot-path perf rollup |
 | `perf_request` | One-request waterfall and attribution |
 | `logs_tail` | Capped recent server logs |
+| `db_query` | Capped read-only database diagnostics for one `SELECT`, `SHOW`, or `EXPLAIN` statement |
 
 ## CLI Boundary
 
@@ -145,6 +147,7 @@ proteum diagnose /dashboard --port 3101
 proteum verify request /dashboard --port 3101
 proteum trace show <requestId> --events --port 3101
 proteum explain owner /dashboard
+proteum db query "SELECT id, email FROM User LIMIT 5" --port 3101
 proteum explain --routes --controllers --full # only when the raw route/controller arrays are required
 ```
 
@@ -163,10 +166,14 @@ trace_show { projectId, requestId }
 trace_latest { projectId }
 perf_request { projectId, query }
 logs_tail { projectId }
+db_query { projectId, sql, limit? }
 ```
 
 After an MCP read succeeds, do not run the equivalent CLI command for the same state, and do not run broad source searches for ownership that MCP already returned. CLI output is for fallback, validation, command evidence, and human-shareable reproductions.
 
+Database diagnostics are intentionally read-only. `db_query` and `proteum db query` support MySQL, MariaDB, PostgreSQL, and PostgreSQL-compatible `DATABASE_URL` protocols. They accept only one `SELECT`, `SHOW`, or `EXPLAIN` statement, return rows, columns, elapsed milliseconds, and cap metadata, and reject multi-statement SQL, `EXPLAIN ANALYZE`, locking reads, file reads/writes, sleep, and benchmark functions.
+
+
 ## Benchmark
 
 The Product `/domains` diagnostic loop measured on May 7, 2026 used `ceil(UTF-8 bytes / 4)` as an output-token estimate:

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.4.1",
+	"version": "2.4.3",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",
@@ -76,6 +76,7 @@
 		"node-cmd": "^5.0.0",
 		"null-loader": "^4.0.1",
 		"path-to-regexp": "^6.2.0",
+		"pg": "^8.21.0",
 		"postcss-loader": "^8.2.0",
 		"preact": "^10.27.1",
 		"preact-render-to-string": "^6.6.1",

package/server/app/container/console/http-client-error-context.test.cjs

@@ -0,0 +1,87 @@
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const coreRoot = path.resolve(__dirname, '../../../..');
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+require('ts-node/register/transpile-only');
+
+const moduleAlias = require('module-alias');
+moduleAlias.addAliases({
+    '@client': path.join(coreRoot, 'client'),
+    '@common': path.join(coreRoot, 'common'),
+    '@server': path.join(coreRoot, 'server'),
+});
+
+const { getHttpClientErrorContext, normalizeBugReportError } = require('./index.ts');
+
+test('wraps got HTTP errors as anomalies with original error context', () => {
+    const error = new Error('Response code 422 (Unprocessable Entity)');
+    error.name = 'HTTPError';
+    error.code = 'ERR_NON_2XX_3XX_RESPONSE';
+    error.timings = {
+        phases: {
+            total: 321,
+        },
+    };
+    error.request = {
+        options: {
+            method: 'GET',
+            url: 'https://api.example.test/ip/2001:db8::1',
+            headers: {
+                'x-key': 'secret-token',
+            },
+        },
+    };
+    error.response = {
+        statusCode: 422,
+        statusMessage: 'Unprocessable Entity',
+        headers: {
+            'set-cookie': 'session=secret',
+        },
+        body: {
+            message: 'Invalid IP address',
+        },
+    };
+
+    const wrapped = normalizeBugReportError(error);
+
+    assert.equal(wrapped.message, 'HTTP client request failed.');
+    assert.equal(wrapped.originalError, error);
+    assert.deepEqual(wrapped.dataForDebugging, {
+        code: 'ERR_NON_2XX_3XX_RESPONSE',
+        statusCode: 422,
+        statusMessage: 'Unprocessable Entity',
+        method: 'GET',
+        url: 'https://api.example.test/ip/2001:db8::1',
+        timings: {
+            phases: {
+                total: 321,
+            },
+        },
+        request: {
+            options: {
+                method: 'GET',
+                url: 'https://api.example.test/ip/2001:db8::1',
+                headers: {
+                    'x-key': 'secret-token',
+                },
+            },
+        },
+        response: {
+            statusCode: 422,
+            statusMessage: 'Unprocessable Entity',
+            headers: {
+                'set-cookie': 'session=secret',
+            },
+            body: {
+                message: 'Invalid IP address',
+            },
+        },
+        options: null,
+    });
+});
+
+test('ignores normal application errors', () => {
+    assert.equal(getHttpClientErrorContext(new Error('Something else failed')), null);
+});

package/server/app/container/console/index.ts

@@ -17,7 +17,7 @@ import Ansi2Html from 'ansi-to-html';
 import type ApplicationContainer from '..';
 import context from '@server/context';
 import type { TDevConsoleLogChannel, TDevConsoleLogEntry, TDevConsoleLogLevel } from '@common/dev/console';
-import type { ServerBug, TCatchedError } from '@common/errors';
+import { Anomaly, type ServerBug, type TCatchedError } from '@common/errors';
 import type { TTraceCallOrigin, TTraceSqlQueryKind } from '@common/dev/requestTrace';
 import type ServerRequest from '@server/services/router/request';
 
@@ -74,6 +74,13 @@ export type TDbQueryLog = ChannelInfos & { date: Date; query: string; time: numb
 export type TLogLevel = keyof typeof logLevels;
 
 export type TJsonLog = { time: Date; level: TLogLevel; args: unknown[]; channel: ChannelInfos };
+type TGotLikeError = Error & {
+    code?: unknown;
+    timings?: unknown;
+    request?: unknown;
+    response?: unknown;
+    options?: unknown;
+};
 
 /*----------------------------------
 - CONST
@@ -111,6 +118,57 @@ var ansi2Html = new Ansi2Html({
 
 type TWrappedConsole = typeof console & { _wrapped?: boolean };
 
+const isRecord = (value: unknown): value is Record<string, unknown> => {
+    return typeof value === 'object' && value !== null;
+};
+
+const firstString = (...values: Array<unknown>): string | null => {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim()) return value;
+        if (value instanceof URL) return value.toString();
+    }
+
+    return null;
+};
+
+export const getHttpClientErrorContext = (error: Error): object | null => {
+    const gotError = error as TGotLikeError;
+    const errorRecord = gotError as unknown as Record<string, unknown>;
+    const code = typeof gotError.code === 'string' ? gotError.code : null;
+    const response = isRecord(gotError.response) ? gotError.response : null;
+    const request = isRecord(gotError.request) ? gotError.request : null;
+    const requestOptions = request && isRecord(request.options) ? request.options : null;
+    const fallbackOptions = isRecord(gotError.options) ? gotError.options : null;
+    const options = requestOptions || fallbackOptions;
+
+    if (error.name !== 'HTTPError' && code !== 'ERR_NON_2XX_3XX_RESPONSE' && !response) return null;
+
+    return {
+        code,
+        statusCode: response && typeof response.statusCode === 'number' ? response.statusCode : null,
+        statusMessage: response && typeof response.statusMessage === 'string' ? response.statusMessage : null,
+        method: options && typeof options.method === 'string' ? options.method : null,
+        url: firstString(
+            response ? response.requestUrl : null,
+            response ? response.url : null,
+            request ? request.requestUrl : null,
+            options ? options.url : null,
+            errorRecord.url,
+        ),
+        timings: gotError.timings || null,
+        request: request || null,
+        response: response || null,
+        options: fallbackOptions,
+    };
+};
+
+export const normalizeBugReportError = (error: TCatchedError): TCatchedError => {
+    const httpClientErrorContext = getHttpClientErrorContext(error);
+    if (!httpClientErrorContext) return error;
+
+    return new Anomaly('HTTP client request failed.', httpClientErrorContext, error);
+};
+
 /*----------------------------------
 - LOGGER
 ----------------------------------*/
@@ -307,7 +365,7 @@ export default class Console {
         // On envoi l'email avant l'insertion dans bla bdd
         // Car cette denrière a plus de chances de provoquer une erreur
         //const logs = this.logs.filter(e => e.channel.channelId === channelId).slice(-100);
-        const inspection = this.getDetailledError(error);
+        const inspection = this.getDetailledError(normalizeBugReportError(error));
 
         // Genertae unique error hash
         const hash = md5(inspection.stacktraces[0]);