proteum 2.4.1 → 2.4.3

package/server/app/devDatabase.ts

@@ -0,0 +1,183 @@
+import mysql from 'mysql2/promise';
+import { Client as PostgresClient } from 'pg';
+import { performance } from 'perf_hooks';
+
+import type {
+    TDatabaseReadQueryColumn,
+    TDatabaseReadQueryResponse,
+    TDatabaseReadQueryRow,
+    TDatabaseReadQueryValue,
+} from '@common/dev/database';
+import { parseMariaDbDatabaseUrl } from '@server/services/prisma/mariadb';
+
+type TDatabaseProtocol = 'mariadb' | 'postgresql';
+
+const normalizeDatabaseValue = (value: unknown): TDatabaseReadQueryValue => {
+    if (value === null || value === undefined) return null;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value;
+    if (typeof value === 'bigint') return value.toString();
+    if (value instanceof Date) return value.toISOString();
+    if (Buffer.isBuffer(value)) return `[Buffer ${value.byteLength} bytes]`;
+
+    return JSON.stringify(value);
+};
+
+const normalizeDatabaseRow = (row: unknown): TDatabaseReadQueryRow => {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) return {};
+
+    return Object.fromEntries(
+        Object.entries(row).map(([key, value]) => [key, normalizeDatabaseValue(value)]),
+    ) as TDatabaseReadQueryRow;
+};
+
+export const databaseProtocolFromUrl = (databaseUrl: string): TDatabaseProtocol => {
+    const { protocol } = new URL(databaseUrl);
+
+    if (protocol === 'mysql:' || protocol === 'mariadb:') return 'mariadb';
+    if (protocol === 'postgres:' || protocol === 'postgresql:') return 'postgresql';
+
+    throw new Error(
+        `Unsupported DATABASE_URL protocol "${protocol}". Proteum database diagnostics support mysql://, mariadb://, postgres://, and postgresql://.`,
+    );
+};
+
+const columnsFromMariaDbFields = (fields: unknown): TDatabaseReadQueryColumn[] =>
+    Array.isArray(fields)
+        ? fields.map((field) => {
+              const candidate = field as { name?: unknown; table?: unknown; type?: unknown };
+
+              return {
+                  name: typeof candidate.name === 'string' ? candidate.name : '',
+                  ...(typeof candidate.table === 'string' && candidate.table ? { table: candidate.table } : {}),
+                  ...(typeof candidate.type === 'number' || typeof candidate.type === 'string' ? { type: candidate.type } : {}),
+              };
+          })
+        : [];
+
+const readMariaDb = async ({
+    databaseUrl,
+    limit,
+    sql,
+    timeoutMs,
+}: {
+    databaseUrl: string;
+    limit: number;
+    sql: string;
+    timeoutMs: number;
+}) => {
+    const connectionConfig = parseMariaDbDatabaseUrl(databaseUrl);
+    const connection = await mysql.createConnection({
+        host: connectionConfig.host,
+        port: connectionConfig.port,
+        user: connectionConfig.user,
+        password: connectionConfig.password,
+        database: connectionConfig.database,
+        connectTimeout: connectionConfig.connectTimeout,
+        multipleStatements: false,
+        supportBigNumbers: true,
+        bigNumberStrings: true,
+        dateStrings: true,
+    });
+
+    try {
+        await connection.query('START TRANSACTION READ ONLY');
+        const [rows, fields] = await connection.query({ sql, timeout: timeoutMs });
+        await connection.rollback();
+
+        const rowList = Array.isArray(rows) ? rows : [];
+        const normalizedRows = rowList.map(normalizeDatabaseRow);
+
+        return {
+            columns: columnsFromMariaDbFields(fields),
+            limited: normalizedRows.length > limit,
+            rowCount: normalizedRows.length,
+            rows: normalizedRows.slice(0, limit),
+        };
+    } catch (error) {
+        try {
+            await connection.rollback();
+        } catch (_rollbackError) {}
+
+        throw error;
+    } finally {
+        await connection.end();
+    }
+};
+
+const readPostgreSql = async ({
+    databaseUrl,
+    limit,
+    sql,
+    timeoutMs,
+}: {
+    databaseUrl: string;
+    limit: number;
+    sql: string;
+    timeoutMs: number;
+}) => {
+    const client = new PostgresClient({
+        connectionString: databaseUrl,
+        statement_timeout: timeoutMs,
+        query_timeout: timeoutMs,
+    });
+
+    try {
+        await client.connect();
+        await client.query('BEGIN READ ONLY');
+        await client.query('SET TRANSACTION READ ONLY');
+        const result = await client.query(sql);
+        await client.query('ROLLBACK');
+
+        const normalizedRows = result.rows.map(normalizeDatabaseRow);
+
+        return {
+            columns: result.fields.map((field) => ({
+                name: field.name,
+                ...(field.tableID ? { table: String(field.tableID) } : {}),
+                type: field.dataTypeID,
+            })),
+            limited: normalizedRows.length > limit,
+            rowCount: normalizedRows.length,
+            rows: normalizedRows.slice(0, limit),
+        };
+    } catch (error) {
+        try {
+            await client.query('ROLLBACK');
+        } catch (_rollbackError) {}
+
+        throw error;
+    } finally {
+        try {
+            await client.end();
+        } catch (_endError) {}
+    }
+};
+
+export const runDatabaseReadQuery = async ({
+    databaseUrl,
+    kind,
+    limit,
+    sql,
+    timeoutMs,
+}: {
+    databaseUrl: string;
+    kind: TDatabaseReadQueryResponse['kind'];
+    limit: number;
+    sql: string;
+    timeoutMs: number;
+}): Promise<TDatabaseReadQueryResponse> => {
+    const startedAt = performance.now();
+    const response =
+        databaseProtocolFromUrl(databaseUrl) === 'postgresql'
+            ? await readPostgreSql({ databaseUrl, limit, sql, timeoutMs })
+            : await readMariaDb({ databaseUrl, limit, sql, timeoutMs });
+    const elapsedMs = Math.max(0, Math.round(performance.now() - startedAt));
+
+    return {
+        ...response,
+        elapsedMs,
+        kind,
+        limit,
+        sql,
+    };
+};

package/server/app/devDiagnostics.ts

@@ -2,7 +2,15 @@ import fs from 'fs-extra';
 import path from 'path';
 
 import type { Application } from './index';
+import { runDatabaseReadQuery } from './devDatabase';
 import type { TDevConsoleLogLevel, TDevConsoleLogsResponse } from '@common/dev/console';
+import {
+    normalizeDatabaseReadLimit,
+    normalizeDatabaseReadTimeoutMs,
+    validateDatabaseReadQuery,
+    type TDatabaseReadQueryInput,
+    type TDatabaseReadQueryResponse,
+} from '@common/dev/database';
 import {
     buildDoctorResponse,
     explainSectionNames,
@@ -88,6 +96,21 @@ export default class DevDiagnosticsRegistry {
         return { logs: this.app.container.Console.listLogs(limit, isConsoleLogLevel(minimumLevel) ? minimumLevel : 'log') };
     }
 
+    public async databaseReadQuery({
+        limit: rawLimit,
+        sql: rawSql,
+        timeoutMs: rawTimeoutMs,
+    }: TDatabaseReadQueryInput): Promise<TDatabaseReadQueryResponse> {
+        const databaseUrl = process.env.DATABASE_URL;
+        if (!databaseUrl) throw new Error('DATABASE_URL is required before running database diagnostics.');
+
+        const { kind, sql } = validateDatabaseReadQuery(rawSql);
+        const limit = normalizeDatabaseReadLimit(rawLimit);
+        const timeoutMs = normalizeDatabaseReadTimeoutMs(rawTimeoutMs);
+
+        return runDatabaseReadQuery({ databaseUrl, kind, limit, sql, timeoutMs });
+    }
+
     private resolveRequestTrace({ path, requestId }: { path?: string; requestId?: string }): TRequestTrace | undefined {
         if (requestId) return this.app.container.Trace.getRequest(requestId);
         if (!path) return this.app.container.Trace.getLatestRequest();

package/server/app/devMcp.ts

@@ -2,6 +2,7 @@ import { buildContractsDoctorResponse } from '@common/dev/contractsDoctor';
 import { buildDoctorResponse } from '@common/dev/diagnostics';
 import { buildOrientationResponse, explainOwner } from '@common/dev/inspection';
 import {
+    compactDatabaseReadQueryResponse,
     buildRuntimeStatusPayload,
     compactDiagnoseResponse,
     compactDoctorResponse,
@@ -189,6 +190,15 @@ export const createRuntimeProteumMcpProvider = ({
                 response: diagnostics().readLogs(limit, level),
             });
         },
+        async dbQuery({ limit, sql, timeoutMs }) {
+            return compactDatabaseReadQueryResponse(
+                await diagnostics().databaseReadQuery({
+                    limit,
+                    sql,
+                    timeoutMs,
+                }),
+            );
+        },
         async readResource(uri) {
             if (uri === 'proteum://runtime/status') return await provider.runtimeStatus({});
             if (uri === 'proteum://instructions/router') return await provider.instructionsResolve({});

package/server/services/prisma/mariadb.ts

@@ -19,7 +19,7 @@ const decodeUrlSegment = (value: string) => {
     return decodeURIComponent(value);
 };
 
-export const createMariaDbAdapter = (databaseUrl: string) => {
+export const parseMariaDbDatabaseUrl = (databaseUrl: string) => {
     const url = new URL(databaseUrl);
 
     if (url.protocol !== 'mysql:' && url.protocol !== 'mariadb:')
@@ -34,7 +34,7 @@ export const createMariaDbAdapter = (databaseUrl: string) => {
     const connectTimeoutSeconds = parseInteger(url.searchParams.get('connect_timeout'));
     const idleTimeoutSeconds = parseInteger(url.searchParams.get('max_idle_connection_lifetime'));
 
-    return new PrismaMariaDb({
+    return {
         host: url.hostname,
         port: parseInteger(url.port) ?? defaultPort,
         user: decodeUrlSegment(url.username),
@@ -43,5 +43,9 @@ export const createMariaDbAdapter = (databaseUrl: string) => {
         connectTimeout: connectTimeoutSeconds ? connectTimeoutSeconds * 1_000 : defaultConnectTimeout,
         idleTimeout: idleTimeoutSeconds ?? defaultIdleTimeout,
         ...(connectionLimit !== undefined ? { connectionLimit } : {}),
-    });
+    };
+};
+
+export const createMariaDbAdapter = (databaseUrl: string) => {
+    return new PrismaMariaDb(parseMariaDbDatabaseUrl(databaseUrl));
 };

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

@@ -606,6 +606,31 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
             }
         });
 
+        routes.post('/__proteum/db/query', async (req, res) => {
+            const sql = typeof req.body?.sql === 'string' ? req.body.sql : '';
+            const rawLimit = Number(req.body?.limit);
+            const rawTimeoutMs = Number(req.body?.timeoutMs);
+
+            try {
+                res.json(
+                    await this.app.getDevDiagnostics().databaseReadQuery({
+                        sql,
+                        limit: Number.isFinite(rawLimit) ? rawLimit : undefined,
+                        timeoutMs: Number.isFinite(rawTimeoutMs) ? rawTimeoutMs : undefined,
+                    }),
+                );
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const isUsageError =
+                    message.includes('SQL') ||
+                    message.includes('allowed') ||
+                    message.includes('not allowed') ||
+                    message.includes('DATABASE_URL');
+
+                res.status(isUsageError ? 400 : 500).json({ error: message });
+            }
+        });
+
         routes.get('/__proteum/diagnose', (req, res) => {
             const readString = (value: unknown) => (Array.isArray(value) ? value[0] : value);
             const readNumber = (value: unknown, fallback: number) => {

package/tests/agents-utils.test.cjs

@@ -102,12 +102,14 @@ test('standalone configure creates tracked instruction files with routing contra
     assert.match(agentsContent, /Read full files only before edits or git writes/);
     assert.match(agentsContent, /explain_summary/);
     assert.match(agentsContent, /\/__proteum\/mcp/);
+    assert.match(agentsContent, /central MCP ready banner/);
     assert.match(agentsContent, /proteum-mcp-v1/);
     assert.match(agentsContent, /## Triggered Instruction Reads/);
     assert.match(agentsContent, /Git lifecycle/);
     assert.match(agentsContent, /read Root contract fallback before any git write/);
     assert.match(agentsContent, /add or update focused unit tests/);
     assert.match(agentsContent, /read Root contract fallback, `CODING_STYLE\.md`, `tests\/AGENTS\.md`/);
+    assert.match(agentsContent, /GEO\/SEO\/crawler\/structured-data\/AI-source changes/);
     assert.match(agentsContent, /MCP-selected previews are enough/);
     assert.doesNotMatch(agentsContent, /Conventional Commits/);
     assert.match(agentsContent, /They are not deleted/);

package/tests/cli-mcp-command.test.cjs

@@ -85,6 +85,63 @@ const runCli = async (args, { cwd }) =>
         child.once('close', (status) => resolve({ status, stdout, stderr }));
     });
 
+const waitForChildOutput = async (child, predicate, timeoutMs = 10000) =>
+    await new Promise((resolve, reject) => {
+        let output = '';
+        let settled = false;
+        let timer;
+        const cleanup = () => {
+            if (timer) clearTimeout(timer);
+            child.stdout.off('data', handleData);
+            child.stderr.off('data', handleData);
+            child.off('close', handleClose);
+        };
+        const settle = (callback) => {
+            if (settled) return;
+            settled = true;
+            cleanup();
+            callback();
+        };
+        const handleData = (chunk) => {
+            output += chunk.toString();
+            if (predicate(output)) settle(() => resolve(output));
+        };
+        const handleClose = (status, signal) => {
+            settle(() => reject(new Error(`Child exited before expected output. status=${status} signal=${signal}\n${output}`)));
+        };
+        timer = setTimeout(() => {
+            child.kill('SIGTERM');
+            settle(() => reject(new Error(`Timed out waiting for expected output.\n${output}`)));
+        }, timeoutMs);
+
+        child.stdout.on('data', handleData);
+        child.stderr.on('data', handleData);
+        child.once('close', handleClose);
+    });
+
+const writeLiveDaemonRecord = (registryDir, { port }) => {
+    const timestamp = new Date().toISOString();
+
+    writeFile(
+        path.join(registryDir, 'router.json'),
+        JSON.stringify(
+            {
+                version: 1,
+                pid: process.pid,
+                port,
+                host: '127.0.0.1',
+                mcpUrl: `http://127.0.0.1:${port}/mcp`,
+                healthUrl: `http://127.0.0.1:${port}/health`,
+                startedAt: timestamp,
+                updatedAt: timestamp,
+                command: [process.execPath, cliBin, 'mcp', '--daemon'],
+            },
+            null,
+            2,
+        ),
+    );
+};
+
 test('top-level help lists the machine-scope mcp router', () => {
     const result = spawnSync(process.execPath, [cliBin, '--help'], {
         cwd: coreRoot,
@@ -110,6 +167,67 @@ test('mcp help describes projectId routing', () => {
     assert.match(output, /--stdio/);
 });
 
+test('mcp daemon launch prints a central MCP connection banner', async () => {
+    const registryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-daemon-launch-'));
+    const reserveServer = http.createServer((req, res) => res.end('reserved'));
+    const port = await listen(reserveServer);
+    await closeServer(reserveServer);
+    const child = spawn(process.execPath, [cliBin, 'mcp', '--daemon', '--port', String(port)], {
+        cwd: coreRoot,
+        env: { ...process.env, PROTEUM_MACHINE_MCP_DIR: registryDir },
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let closed = false;
+    child.once('close', () => {
+        closed = true;
+    });
+
+    try {
+        const output = await waitForChildOutput(child, (value) =>
+            value.includes(`Connect MCP client (HTTP): http://127.0.0.1:${port}/mcp`),
+        );
+
+        assert.match(output, /CENTRAL MCP READY/);
+        assert.match(output, /Launched central MCP server/);
+    } finally {
+        if (!closed) {
+            child.kill('SIGTERM');
+            await new Promise((resolve) => child.once('close', resolve));
+        }
+    }
+});
+
+test('mcp daemon reuse prints a central MCP connection banner', () => {
+    const registryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-daemon-reuse-'));
+    const port = 37977;
+    writeLiveDaemonRecord(registryDir, { port });
+
+    const result = spawnSync(process.execPath, [cliBin, 'mcp', '--daemon', '--port', String(port)], {
+        cwd: coreRoot,
+        encoding: 'utf8',
+        env: { ...process.env, PROTEUM_MACHINE_MCP_DIR: registryDir },
+    });
+    const output = `${result.stdout}\n${result.stderr}`;
+
+    assert.equal(result.status, 0);
+    assert.match(output, /CENTRAL MCP READY/);
+    assert.match(output, /Connected to central MCP server/);
+    assert.match(output, new RegExp(`Connect MCP client \\(HTTP\\): http://127\\.0\\.0\\.1:${port}/mcp`));
+});
+
+test('db help describes read-only SQL diagnostics', () => {
+    const result = spawnSync(process.execPath, [cliBin, 'db', '--help'], {
+        cwd: coreRoot,
+        encoding: 'utf8',
+    });
+    const output = `${result.stdout}\n${result.stderr}`;
+
+    assert.equal(result.status, 0);
+    assert.match(output, /SELECT, SHOW, and EXPLAIN/);
+    assert.match(output, /--limit/);
+    assert.match(output, /--timeout/);
+});
+
 test('explain help describes compact section summaries', () => {
     const result = spawnSync(process.execPath, [cliBin, 'explain', '--help'], {
         cwd: coreRoot,
@@ -219,6 +337,58 @@ test('runtime status reports occupied configured port without probing page bodie
     }
 });
 
+test('db query posts one read-only SQL statement to the running dev endpoint', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-cli-db-'));
+    const appRoot = path.join(repoRoot, 'apps', 'product');
+    let receivedBody = '';
+    const server = http.createServer((req, res) => {
+        if (req.url === '/__proteum/db/query' && req.method === 'POST') {
+            req.on('data', (chunk) => {
+                receivedBody += chunk.toString();
+            });
+            req.on('end', () => {
+                res.setHeader('content-type', 'application/json');
+                res.end(
+                    JSON.stringify({
+                        kind: 'select',
+                        sql: 'SELECT 1',
+                        elapsedMs: 7,
+                        limit: 5,
+                        limited: false,
+                        rowCount: 1,
+                        columns: [{ name: 'value', type: 3 }],
+                        rows: [{ value: 1 }],
+                    }),
+                );
+            });
+            return;
+        }
+
+        res.statusCode = 404;
+        res.end('not found');
+    });
+    const port = await listen(server);
+
+    try {
+        createProteumApp(appRoot, { routerPort: port });
+
+        const result = await runCli(['db', 'query', 'SELECT 1', '--limit', '5'], {
+            cwd: appRoot,
+        });
+        const payload = JSON.parse(result.stdout);
+        const body = JSON.parse(receivedBody);
+
+        assert.equal(result.status, 0);
+        assert.equal(body.sql, 'SELECT 1');
+        assert.equal(body.limit, 5);
+        assert.equal(payload.ok, true);
+        assert.equal(payload.data.elapsedMs, 7);
+        assert.deepEqual(payload.data.rows, [{ value: 1 }]);
+    } finally {
+        await closeServer(server);
+    }
+});
+
 test('runtime status avoids starting a second dev server when the same app owns the port', async () => {
     const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-cli-same-port-'));
     const appRoot = path.join(repoRoot, 'apps', 'product');

package/tests/mcp.test.cjs

@@ -21,6 +21,11 @@ const {
     resolveInstructionRouting,
 } = require('../common/dev/mcpPayloads.ts');
 const { createProteumMcpServer } = require('../common/dev/mcpServer.ts');
+const {
+    normalizeDatabaseReadLimit,
+    validateDatabaseReadQuery,
+} = require('../common/dev/database.ts');
+const { databaseProtocolFromUrl } = require('../server/app/devDatabase.ts');
 const { createProteumMachineMcpServer } = require('../cli/mcp/router.ts');
 const {
     createDevSessionRecord,
@@ -126,6 +131,32 @@ test('instruction routing returns compact selected files for a page query', () =
     assert.equal(payload.data.readWhen.some((entry) => entry.file && entry.file.endsWith('diagnostics.md')), true);
 });
 
+test('database read query policy allows only capped SELECT SHOW and EXPLAIN diagnostics', () => {
+    assert.deepEqual(validateDatabaseReadQuery(' SELECT 1; '), { kind: 'select', sql: 'SELECT 1' });
+    assert.deepEqual(validateDatabaseReadQuery('/* plan */ EXPLAIN SELECT * FROM User'), {
+        kind: 'explain',
+        sql: '/* plan */ EXPLAIN SELECT * FROM User',
+    });
+    assert.deepEqual(validateDatabaseReadQuery('SHOW TABLES'), { kind: 'show', sql: 'SHOW TABLES' });
+    assert.equal(normalizeDatabaseReadLimit(999), 500);
+
+    assert.throws(() => validateDatabaseReadQuery('UPDATE User SET role = "admin"'), /Only SELECT, SHOW, and EXPLAIN/);
+    assert.throws(() => validateDatabaseReadQuery('SELECT 1; DROP TABLE User'), /Only one read-only SQL statement/);
+    assert.throws(() => validateDatabaseReadQuery('EXPLAIN ANALYZE SELECT * FROM User'), /EXPLAIN ANALYZE/);
+    assert.throws(() => validateDatabaseReadQuery('SELECT LOAD_FILE("/etc/passwd")'), /file-read/);
+    assert.throws(() => validateDatabaseReadQuery("SELECT pg_read_file('/etc/passwd')"), /file-read/);
+    assert.throws(() => validateDatabaseReadQuery('SELECT * FROM "User" FOR SHARE'), /Locking read/);
+    assert.throws(() => validateDatabaseReadQuery('SELECT pg_sleep(1)'), /Sleep and benchmark/);
+});
+
+test('database diagnostics support MySQL MariaDB and PostgreSQL URLs', () => {
+    assert.equal(databaseProtocolFromUrl('mysql://user:pass@localhost:3306/app'), 'mariadb');
+    assert.equal(databaseProtocolFromUrl('mariadb://user:pass@localhost:3306/app'), 'mariadb');
+    assert.equal(databaseProtocolFromUrl('postgres://user:pass@localhost:5432/app'), 'postgresql');
+    assert.equal(databaseProtocolFromUrl('postgresql://user:pass@localhost:5432/app'), 'postgresql');
+    assert.throws(() => databaseProtocolFromUrl('sqlite://local.db'), /postgresql/);
+});
+
 test('instruction routing promotes triggered full instruction files', () => {
     const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-trigger-app-'));
     const fallbackRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-trigger-core-'));
@@ -367,6 +398,7 @@ test('trace payload keeps default output compact and paginates full details', ()
 test('MCP server registers the Proteum read-only tool contract', async () => {
     const payload = createMcpPayload({ summary: 'ok', data: { value: 1 } });
     const provider = {
+        dbQuery: async () => payload,
         diagnose: async () => payload,
         doctor: async () => payload,
         explainSummary: async () => payload,
@@ -396,6 +428,7 @@ test('MCP server registers the Proteum read-only tool contract', async () => {
     assert.equal(tools.tools.some((tool) => tool.name === 'runtime_status'), true);
     assert.equal(tools.tools.some((tool) => tool.name === 'workflow_start'), true);
     assert.equal(tools.tools.some((tool) => tool.name === 'route_candidates'), true);
+    assert.equal(tools.tools.some((tool) => tool.name === 'db_query'), true);
     assert.match(result.content[0].text, /proteum-mcp-v1/);
     assert.match(resource.contents[0].text, /proteum-mcp-v1/);