@promptbook/cli 0.112.0-118 → 0.112.0-119

package/apps/agents-server/src/app/api/page-preview/check/route.ts

@@ -0,0 +1,31 @@
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { assertsError } from '../../../../../../../src/errors/assertsError';
+import { checkIfUrlCanBeEmbedded } from '../../../../utils/iframe/checkIfUrlCanBeEmbedded';
+
+/**
+ * Checks whether a given URL can be embedded in an iframe by inspecting
+ * `X-Frame-Options` and `Content-Security-Policy` `frame-ancestors` headers.
+ *
+ * Query parameters:
+ * - `url` — the fully-qualified HTTP(S) URL to check
+ *
+ * Returns `{ canEmbed: boolean }`.
+ */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+    const url = request.nextUrl.searchParams.get('url');
+
+    if (!url) {
+        return NextResponse.json({ error: 'Missing required query parameter: url' }, { status: 400 });
+    }
+
+    try {
+        const canEmbed = await checkIfUrlCanBeEmbedded(url);
+        return NextResponse.json({ canEmbed });
+    } catch (error) {
+        assertsError(error);
+        console.warn('Failed to check if URL can be embedded:', error.message);
+        // When the check fails, allow the iframe to try — the browser will handle it
+        return NextResponse.json({ canEmbed: true });
+    }
+}

package/apps/agents-server/src/app/api/page-preview/screenshot/route.ts

@@ -0,0 +1,57 @@
+import { $provideBrowserForServer } from '@/src/tools/$provideBrowserForServer';
+import { serializeError } from '@promptbook-local/utils';
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { assertsError } from '../../../../../../../src/errors/assertsError';
+
+/**
+ * Takes a screenshot of the given URL using a headless browser.
+ *
+ * Query parameters:
+ * - `url` — the fully-qualified HTTP(S) URL to screenshot
+ *
+ * Returns a PNG image.
+ */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+    const url = request.nextUrl.searchParams.get('url');
+
+    if (!url) {
+        return NextResponse.json({ error: 'Missing required query parameter: url' }, { status: 400 });
+    }
+
+    let parsedUrl: URL;
+    try {
+        parsedUrl = new URL(url);
+    } catch {
+        return NextResponse.json({ error: 'Invalid URL' }, { status: 400 });
+    }
+
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+        return NextResponse.json({ error: 'Only http and https URLs are supported' }, { status: 400 });
+    }
+
+    try {
+        const browserContext = await $provideBrowserForServer();
+        const page = await browserContext.newPage();
+
+        try {
+            await page.setViewportSize({ width: 1280, height: 800 });
+            await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+            const screenshotBuffer = await page.screenshot({ type: 'png' });
+
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return new NextResponse(new Blob([screenshotBuffer as any]), {
+                headers: {
+                    'Content-Type': 'image/png',
+                    'Cache-Control': 'public, max-age=300',
+                },
+            });
+        } finally {
+            await page.close().catch(() => {});
+        }
+    } catch (error) {
+        assertsError(error);
+        console.error('Error taking page screenshot:', error);
+        return NextResponse.json({ error: serializeError(error) }, { status: 500 });
+    }
+}

package/apps/agents-server/src/app/api/upload/route.ts

@@ -15,6 +15,7 @@ import {
 } from '../../../tools/$provideCdnForServer';
 import { $provideServer } from '../../../tools/$provideServer';
 import { getSafeCdnPath } from '../../../utils/cdn/utils/getSafeCdnPath';
+import { getUserFileCdnKey } from '../../../utils/cdn/utils/getUserFileCdnKey';
 import { FILE_SECURITY_CHECKERS } from '../../../file-security-checkers';
 import { getUserIdFromRequest } from '../../../utils/getUserIdFromRequest';
 import { getMaxFileUploadSizeBytes } from '../../../utils/serverLimits';
@@ -223,7 +224,7 @@ export async function POST(request: NextRequest) {
         const providedServer = await $provideServer();
         assertFileUploadAvailable(providedServer);
 
-        const { file, pathname, purpose, contentType } = await parseUploadRequest(request);
+        const { file, purpose, contentType } = await parseUploadRequest(request);
         const fileBuffer = Buffer.from(await file.arrayBuffer());
         const maxFileSize = await getMaxFileUploadSizeBytes();
 
@@ -237,6 +238,14 @@ export async function POST(request: NextRequest) {
             );
         }
 
+        // [✨🏣] Compute a content-addressed CDN key so the public URL contains
+        // the file hash and does not expose the internal S3 bucket or path prefix.
+        const rawKey = getUserFileCdnKey(fileBuffer, file.name);
+        const pathname = getSafeCdnPath({
+            pathname: rawKey,
+            pathPrefix: process.env.NEXT_PUBLIC_CDN_PATH_PREFIX,
+        });
+
         const cdn = $provideCdnForServer({
             cdnPublicUrl: resolveCdnPublicUrlForServer(providedServer.publicUrl),
         });

package/apps/agents-server/src/app/s3/[first]/[second]/[hash]/[filename]/route.ts

@@ -0,0 +1,52 @@
+import { NextRequest, NextResponse } from 'next/server';
+import {
+    $provideCdnForServer,
+    resolveCdnPublicUrlForServer,
+} from '../../../../../../tools/$provideCdnForServer';
+import { $provideServer } from '../../../../../../tools/$provideServer';
+
+/**
+ * Serves files stored under the hash-based CDN key format:
+ * `{hash[0]}/{hash[1]}/{sha256-hash}/{filename}`
+ *
+ * This route is reached when nginx routes a request matching
+ * `^/s3/[0-9a-f]/[0-9a-f]/[0-9a-f]{64}/` to Next.js instead of VersityGW,
+ * which keeps the internal S3 bucket and path prefix hidden from the public URL.
+ *
+ * [✨🏣] Companion route for `getUserFileCdnKey` and the `publicCdnBaseUrl`
+ * configuration in `$provideCdnForServer`.
+ */
+export async function GET(
+    _request: NextRequest,
+    {
+        params,
+    }: {
+        params: Promise<{
+            first: string;
+            second: string;
+            hash: string;
+            filename: string;
+        }>;
+    },
+) {
+    const { first, second, hash, filename } = await params;
+    const key = `${first}/${second}/${hash}/${filename}`;
+
+    const providedServer = await $provideServer();
+    const cdn = $provideCdnForServer({
+        cdnPublicUrl: resolveCdnPublicUrlForServer(providedServer.publicUrl),
+    });
+
+    const file = await cdn.getItem(key);
+
+    if (!file) {
+        return new NextResponse(null, { status: 404 });
+    }
+
+    return new NextResponse(file.data, {
+        headers: {
+            'Content-Type': file.type,
+            'Cache-Control': 'public, max-age=31536000, immutable',
+        },
+    });
+}

package/apps/agents-server/src/database/$provideClientSql.ts

@@ -31,6 +31,33 @@ export type ClientSqlExecutor = ClientSql & {
     readonly raw: ClientSqlRaw;
 };
 
+/**
+ * Maximum number of PostgreSQL connections in the shared pool.
+ *
+ * Configurable via `DATABASE_POOL_MAX` environment variable.
+ * Defaults to 20 which comfortably handles concurrent chat-stream polling loads.
+ *
+ * @private internal constant of Agents Server database layer
+ */
+const DATABASE_POOL_MAX = Math.max(1, parseInt(process.env.DATABASE_POOL_MAX || '20', 10));
+
+/**
+ * Milliseconds to wait for a free pool connection before failing.
+ *
+ * Without a timeout the default `pg` behaviour is to queue requests indefinitely,
+ * which causes the server to become unresponsive under pool exhaustion.
+ *
+ * @private internal constant of Agents Server database layer
+ */
+const POOL_CONNECTION_TIMEOUT_MS = 15_000;
+
+/**
+ * Milliseconds an idle client stays in the pool before being closed.
+ *
+ * @private internal constant of Agents Server database layer
+ */
+const POOL_IDLE_TIMEOUT_MS = 30_000;
+
 /**
  * Shared PostgreSQL pool reused across all requests in the server process.
  *
@@ -52,6 +79,16 @@ export async function $provideClientSql(): Promise<ClientSqlExecutor> {
         clientPool = new Pool({
             connectionString: resolvePostgresConnectionString(),
             ssl: { rejectUnauthorized: false },
+            max: DATABASE_POOL_MAX,
+            idleTimeoutMillis: POOL_IDLE_TIMEOUT_MS,
+            connectionTimeoutMillis: POOL_CONNECTION_TIMEOUT_MS,
+            allowExitOnIdle: true,
+        });
+
+        // Prevent unhandled errors from crashing the pool or the process.
+        // Individual query errors are still thrown at the call site.
+        clientPool.on('error', (error) => {
+            console.error('[database] Unexpected error on idle PostgreSQL client:', error);
         });
     }
 

package/apps/agents-server/src/database/$provideSupabaseForServer.ts

@@ -4,6 +4,44 @@ import { isAgentsServerSqliteMode } from './agentsServerDatabaseMode';
 import { $provideLocalSqliteSupabase } from './sqlite/$provideLocalSqliteSupabase';
 import { AgentsServerDatabase } from './schema';
 
+/**
+ * Hard timeout for every Supabase HTTP request.
+ *
+ * Without this, a slow or unreachable PostgREST endpoint causes requests to
+ * hang indefinitely, eventually making the server appear unresponsive.
+ *
+ * @private internal constant of Agents Server database layer
+ */
+const SUPABASE_REQUEST_TIMEOUT_MS = 30_000;
+
+/**
+ * Wraps the native `fetch` with a per-request timeout so Supabase queries
+ * always resolve (with an error) within `SUPABASE_REQUEST_TIMEOUT_MS`.
+ *
+ * When the caller already passes an AbortSignal the request is aborted when
+ * either that signal fires or the timeout fires — whichever comes first.
+ *
+ * Uses manual composition instead of `AbortSignal.any` for Node.js 18 compatibility
+ * (`AbortSignal.any` is only available in Node.js 20.3+).
+ *
+ * @private internal helper of Agents Server database layer
+ */
+function fetchWithSupabaseTimeout(url: RequestInfo | URL, options?: RequestInit): Promise<Response> {
+    const existingSignal = options?.signal instanceof AbortSignal ? options.signal : null;
+
+    if (!existingSignal) {
+        return fetch(url, { ...options, signal: AbortSignal.timeout(SUPABASE_REQUEST_TIMEOUT_MS) });
+    }
+
+    // Compose the caller signal with the timeout: abort when either fires.
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    existingSignal.addEventListener('abort', abort, { once: true });
+    AbortSignal.timeout(SUPABASE_REQUEST_TIMEOUT_MS).addEventListener('abort', abort, { once: true });
+
+    return fetch(url, { ...options, signal: controller.signal });
+}
+
 /**
  * Internal cache for `$provideSupabaseForServer`
  *
@@ -42,6 +80,9 @@ export function $provideSupabaseForServer(): SupabaseClient<AgentsServerDatabase
                     autoRefreshToken: false,
                     persistSession: false,
                 },
+                global: {
+                    fetch: fetchWithSupabaseTimeout,
+                },
             },
         );
     }

package/apps/agents-server/src/tools/$provideCdnForServer.ts

@@ -74,6 +74,13 @@ function createCdnStorageForServer(cdnPublicUrl: URL): IIFilesStorageWithCdn {
             gzip: true,
             forcePathStyle: process.env.CDN_FORCE_PATH_STYLE === 'true',
             region: resolveS3CompatibleStorageRegion(),
+            // [✨🏣] For self-contained S3: hash-based CDN keys get a public URL that
+            // omits the internal bucket and pathPrefix so users can't infer the storage
+            // structure. The `/s3/` segment is preserved so nginx routes those requests
+            // to the Next.js hash-file route instead of directly to VersityGW.
+            publicCdnBaseUrl: isSelfContainedS3StorageSelected()
+                ? resolveHashBasedPublicCdnBaseUrl(cdnPublicUrl)
+                : undefined,
         });
     }
 
@@ -84,6 +91,23 @@ function createCdnStorageForServer(cdnPublicUrl: URL): IIFilesStorageWithCdn {
     });
 }
 
+/**
+ * Derives the public base URL used for hash-based file URLs on self-contained S3.
+ *
+ * Strips the bucket segment from the configured CDN URL so that the public URL
+ * exposes only the `/s3/` prefix — the internal bucket name and path prefix
+ * remain hidden from users.
+ *
+ * Example: `https://s24.ptbk.io/s3/promptbook-files/` → `https://s24.ptbk.io/s3/`
+ *
+ * [✨🏣] Companion to `isHashBasedCdnKey` in `DigitalOceanSpaces`.
+ *
+ * @private helper of `createCdnStorageForServer`
+ */
+function resolveHashBasedPublicCdnBaseUrl(cdnPublicUrl: URL): URL {
+    return new URL('/s3/', cdnPublicUrl);
+}
+
 /**
  * Resolves the CDN public URL from environment configuration.
  *

package/apps/agents-server/src/utils/cdn/classes/DigitalOceanSpaces.ts

@@ -19,6 +19,16 @@ type IDigitalOceanSpacesConfig = {
     readonly forcePathStyle?: boolean;
     readonly region?: string;
 
+    /**
+     * When set, `getItemUrl` generates `new URL(key, publicCdnBaseUrl)` for
+     * hash-based CDN keys instead of the default formula that prepends the
+     * `pathPrefix`. This allows self-contained S3 to expose an unguessable URL
+     * that hides the internal bucket name and path prefix.
+     *
+     * [✨🏣] Used by self-contained S3 to serve files via the Next.js hash route.
+     */
+    readonly publicCdnBaseUrl?: URL;
+
     // TODO: [⛳️] Probbably prefix should be in this config not on the consumer side
 };
 
@@ -27,7 +37,7 @@ type IDigitalOceanSpacesConfig = {
  */
 export class DigitalOceanSpaces implements IIFilesStorageWithCdn {
     public get cdnPublicUrl() {
-        return this.config.cdnPublicUrl;
+        return this.config.publicCdnBaseUrl ?? this.config.cdnPublicUrl;
     }
 
     private s3: S3Client;
@@ -45,7 +55,13 @@ export class DigitalOceanSpaces implements IIFilesStorageWithCdn {
     }
 
     public getItemUrl(key: string): URL {
-        return new URL(this.config.pathPrefix + '/' + key, this.cdnPublicUrl);
+        // [✨🏣] For hash-based keys, omit the pathPrefix from the public URL so
+        // the internal S3 structure (bucket, prefix, upload directory) is hidden.
+        if (this.config.publicCdnBaseUrl && isHashBasedCdnKey(key)) {
+            return new URL(key, this.config.publicCdnBaseUrl);
+        }
+
+        return new URL(this.config.pathPrefix + '/' + key, this.config.cdnPublicUrl);
     }
 
     public async getItem(key: string): Promise<IFile | null> {
@@ -122,6 +138,18 @@ export class DigitalOceanSpaces implements IIFilesStorageWithCdn {
     }
 }
 
+/**
+ * Returns `true` when `key` matches the hash-based CDN key format produced by
+ * `getUserFileCdnKey`: `{hex}/{hex}/{sha256-64-chars}/{filename}`.
+ *
+ * [✨🏣] Used by `getItemUrl` to decide whether to strip the internal path prefix.
+ *
+ * @private helper of `DigitalOceanSpaces`
+ */
+function isHashBasedCdnKey(key: string): boolean {
+    return /^[0-9a-f]\/[0-9a-f]\/[0-9a-f]{64}\//.test(key);
+}
+
 /**
  * Normalizes endpoint values from legacy host-only configuration and full S3 URLs.
  *

package/apps/agents-server/src/utils/cdn/utils/getUserFileCdnKey.ts

@@ -2,10 +2,15 @@ import hexEncoder from 'crypto-js/enc-hex';
 import sha256 from 'crypto-js/sha256';
 import type { string_uri } from '../../../../../../src/types/typeAliases';
 import { titleToName } from '../../../../../../src/utils/normalization/titleToName';
-import { nameToSubfolderPath } from './nameToSubfolderPath';
 
 /**
- * Generates a path for the user content
+ * Generates a content-addressed path for user-uploaded files.
+ *
+ * The returned key uses the SHA-256 hash of the file buffer so the URL is
+ * unguessable and does not expose internal storage structure (bucket, prefix,
+ * or upload directory). The first two hex characters are used as single-level
+ * shard directories, matching the same convention as the public URL served by
+ * the hash-based file route.
  */
 export function getUserFileCdnKey(file: Buffer, originalFilename: string): string_uri {
     const hash = sha256(hexEncoder.parse(file.toString('hex'))).toString(/* hex */);
@@ -18,7 +23,9 @@ export function getUserFileCdnKey(file: Buffer, originalFilename: string): strin
     const filename = name + '.' + extension;
     // <- Note: [⛳️] Preserving original file name
 
-    return `user/files/${nameToSubfolderPath(hash).join('/')}/${filename}`;
+    // [✨🏣] Hash-based key: {hash[0]}/{hash[1]}/{fullHash}/{filename}
+    // The single-char shard dirs and full hash hide the internal S3 structure.
+    return `${hash[0]}/${hash[1]}/${hash}/${filename}`;
 }
 
 // TODO: [🌍] Unite this logic in one place

package/apps/agents-server/src/utils/iframe/checkIfUrlCanBeEmbedded.ts

@@ -0,0 +1,68 @@
+/**
+ * Parses the X-Frame-Options header value and returns whether embedding is allowed.
+ *
+ * Some servers set multiple values (e.g. "DENY, SAMEORIGIN") which results in a
+ * comma-separated string. Any DENY or SAMEORIGIN token blocks embedding.
+ */
+function canEmbedByXFrameOptions(headerValue: string): boolean {
+    const values = headerValue
+        .split(',')
+        .map((v) => v.trim().toUpperCase());
+    return !values.some((v) => v === 'DENY' || v === 'SAMEORIGIN');
+}
+
+/**
+ * Parses the Content-Security-Policy header and checks the `frame-ancestors` directive.
+ *
+ * Returns false when `frame-ancestors` is present and does not include a wildcard or
+ * protocol-level allow (`*`, `https:`, `http:`).
+ */
+function canEmbedByCsp(cspHeader: string): boolean {
+    const match = cspHeader.match(/frame-ancestors\s+([^;]+)/i);
+    if (!match) {
+        return true;
+    }
+
+    const directive = (match[1] ?? '').trim();
+    const tokens = directive.split(/\s+/);
+
+    for (const token of tokens) {
+        if (token === '*' || token === 'https:' || token === 'http:') {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Checks whether a given HTTP(S) URL allows being embedded in an iframe by
+ * inspecting `X-Frame-Options` and `Content-Security-Policy` `frame-ancestors`.
+ *
+ * Returns `true` when the page is embeddable, `false` when it is blocked.
+ * Throws when the URL is not HTTP(S) or the network request fails.
+ */
+export async function checkIfUrlCanBeEmbedded(url: string): Promise<boolean> {
+    const parsedUrl = new URL(url);
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+        throw new Error(`Only http and https URLs are supported, got: ${parsedUrl.protocol}`);
+    }
+
+    const response = await fetch(url, {
+        method: 'HEAD',
+        signal: AbortSignal.timeout(10_000),
+        redirect: 'follow',
+    });
+
+    const xFrameOptions = response.headers.get('X-Frame-Options');
+    if (xFrameOptions !== null && !canEmbedByXFrameOptions(xFrameOptions)) {
+        return false;
+    }
+
+    const csp = response.headers.get('Content-Security-Policy');
+    if (csp !== null && !canEmbedByCsp(csp)) {
+        return false;
+    }
+
+    return true;
+}

package/esm/index.es.js

@@ -58,7 +58,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-118';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-119';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -3272,6 +3272,16 @@ const AGENTS_SERVER_NEXT_BUILD_ID_FILENAME = 'BUILD_ID';
  * @private internal constant of `ptbk agents-server`
  */
 const DEFAULT_AGENTS_SERVER_NEXT_DIST_DIRECTORY_NAME = '.next';
+/**
+ * Node.js heap size limit (in MiB) injected into `NODE_OPTIONS` for the Next.js production build.
+ *
+ * Next.js webpack peaks at ~1.9 GiB on a fresh install; the Node.js default cap is ~1.7 GiB,
+ * which causes an OOM crash on first-run VPS installations where swap is the primary resource.
+ * Raising the limit lets the build complete on the first attempt.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB = 4096;
 /**
  * Environment variable passed to the bundled Next app so webpack can resolve dependencies
  * installed beside `ptbk` even when the app sources are materialized into a project cache.
@@ -3669,7 +3679,10 @@ async function runNextBuild(options) {
         var _a, _b;
         const buildProcess = spawn(process.execPath, [options.nextCliPath, 'build'], {
             cwd: options.appPath,
-            env: options.environment,
+            env: {
+                ...options.environment,
+                NODE_OPTIONS: mergeNodeOptionsWithHeapSize(options.environment.NODE_OPTIONS, AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB),
+            },
             stdio: ['ignore', 'pipe', 'pipe'],
         });
         (_a = buildProcess.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (chunk) => {
@@ -3688,6 +3701,16 @@ async function runNextBuild(options) {
         });
     });
 }
+/**
+ * Prepends `--max-old-space-size=<mib>` to `NODE_OPTIONS` unless the caller already set one.
+ */
+function mergeNodeOptionsWithHeapSize(existingNodeOptions, maxOldSpaceMib) {
+    if (existingNodeOptions !== undefined && /--max-old-space-size[= ]/u.test(existingNodeOptions)) {
+        return existingNodeOptions;
+    }
+    const heapFlag = `--max-old-space-size=${maxOldSpaceMib}`;
+    return existingNodeOptions ? `${heapFlag} ${existingNodeOptions}` : heapFlag;
+}
 /**
  * Sends one Next build output chunk through the caller handler or to the foreground terminal.
  */
@@ -58459,7 +58482,7 @@ class OpenAiVectorStoreKnowledgeSourcePreparer {
                 return { skippedReason: 'invalid_data_url' };
             }
             return {
-                file: new File([parsed.buffer], parsed.filename, {
+                file: new File([new Uint8Array(parsed.buffer)], parsed.filename, {
                     type: parsed.mimeType,
                 }),
                 sizeBytes: parsed.buffer.length,