@promptbook/cli 0.112.0-88 → 0.112.0-90

package/src/version.ts

@@ -16,11 +16,11 @@ export const BOOK_LANGUAGE_VERSION: string_semantic_version = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-export const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version = '0.112.0-88';
+export const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version = '0.112.0-90';
 
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.112.0-82`).
+ * It follows semantic versioning (e.g., `0.112.0-89`).
  *
  * @generated
  */

package/src/versions.txt

@@ -1125,3 +1125,5 @@
 0.112.0-81
 0.112.0-82
 0.112.0-88
+0.112.0-89
+0.112.0-90

package/umd/apps/agents-server/src/utils/serverRegistry.d.ts

@@ -65,6 +65,12 @@ export declare function listRegisteredServers(supabase: Pick<SupabaseClient, 'fr
 export declare function listRegisteredServersUsingServiceRole(options?: {
     readonly forceRefresh?: boolean;
 }): Promise<Array<ServerRecord>>;
+/**
+ * Loads virtual server records from the comma-separated `SERVERS` environment variable.
+ *
+ * @returns Server records with deterministic table prefixes derived from normalized domains.
+ */
+export declare function listEnvironmentRegisteredServers(): Array<ServerRecord>;
 /**
  * Finds one registered server by incoming host header.
  *

package/umd/index.umd.js

@@ -60,7 +60,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-88';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-90';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -3104,6 +3104,31 @@
      * @private internal constant of `ptbk agents-server`
      */
     const DEFAULT_AGENTS_SERVER_NEXT_DIST_DIRECTORY_NAME = '.next';
+    /**
+     * 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.
+     *
+     * @private internal constant of `ptbk agents-server`
+     */
+    const PTBK_AGENTS_SERVER_NODE_MODULES_PATH_ENV = 'PTBK_AGENTS_SERVER_NODE_MODULES_PATH';
+    /**
+     * Environment variable used only by the CLI-owned production build.
+     *
+     * @private internal constant of `ptbk agents-server`
+     */
+    const PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION_ENV = 'PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION';
+    /**
+     * Runtime copy metadata filename stored in the project-local materialized app root.
+     *
+     * @private internal constant of `ptbk agents-server`
+     */
+    const AGENTS_SERVER_MATERIALIZED_RUNTIME_CACHE_FILENAME = '.ptbk-agents-server-runtime-cache.json';
+    /**
+     * Directory segment used for Node package installs.
+     *
+     * @private internal constant of `ptbk agents-server`
+     */
+    const NODE_MODULES_DIRECTORY_NAME = 'node_modules';
     /**
      * Runtime paths copied into the CLI package and used by the Agents Server production build.
      *
@@ -3148,26 +3173,33 @@
      */
     async function ensureAgentsServerBuild(options = {}) {
         var _a, _b, _c, _d;
-        const appPath = (_a = options.appPath) !== null && _a !== void 0 ? _a : (await resolveAgentsServerAppPath());
-        const environment = (_b = options.environment) !== null && _b !== void 0 ? _b : process.env;
+        const environment = (_a = options.environment) !== null && _a !== void 0 ? _a : process.env;
         const nextCliPath = resolveNextCliPath();
+        const nodeModulesPath = resolveNodeModulesPath(nextCliPath);
+        const appPath = await resolveAgentsServerBuildAppPath({
+            sourceAppPath: (_b = options.appPath) !== null && _b !== void 0 ? _b : (await resolveAgentsServerAppPath()),
+            nodeModulesPath,
+        });
+        const buildEnvironment = createAgentsServerRuntimeEnvironment(environment, nodeModulesPath, {
+            isNextValidationIgnored: isAgentsServerAppPathMaterialized(appPath),
+        });
         if (!options.isBuildForced &&
             (await isAgentsServerBuildCacheCurrent({
                 appPath,
-                environment,
+                environment: buildEnvironment,
             }))) {
             (_c = options.onBuildEvent) === null || _c === void 0 ? void 0 : _c.call(options, 'Using the cached Agents Server Next app build.');
-            return { appPath, nextCliPath };
+            return { appPath, nextCliPath, nodeModulesPath };
         }
         (_d = options.onBuildEvent) === null || _d === void 0 ? void 0 : _d.call(options, 'Building the Agents Server Next app.');
         await runNextBuild({
             appPath,
-            environment,
+            environment: buildEnvironment,
             nextCliPath,
             onBuildOutput: options.onBuildOutput,
         });
-        await writeAgentsServerBuildCache({ appPath, environment });
-        return { appPath, nextCliPath };
+        await writeAgentsServerBuildCache({ appPath, environment: buildEnvironment });
+        return { appPath, nextCliPath, nodeModulesPath };
     }
     /**
      * Returns true when the production build marker and source fingerprint still match.
@@ -3223,6 +3255,165 @@
             ${candidates.map((candidate) => `- \`${candidate}\``).join('\n')}
         `));
     }
+    /**
+     * Adds dependency-resolution environment required by the materialized Agents Server runtime.
+     *
+     * @private internal utility of `ptbk agents-server`
+     */
+    function createAgentsServerRuntimeEnvironment(environment, nodeModulesPath, options = {}) {
+        return {
+            ...environment,
+            NODE_PATH: mergeNodePath(nodeModulesPath, environment.NODE_PATH),
+            [PTBK_AGENTS_SERVER_NODE_MODULES_PATH_ENV]: nodeModulesPath,
+            ...(options.isNextValidationIgnored
+                ? {
+                    [PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION_ENV]: 'true',
+                }
+                : {}),
+        };
+    }
+    /**
+     * Uses the source checkout app directly, but copies npm-packaged app sources out of `node_modules`.
+     *
+     * @private internal utility of `ptbk agents-server`
+     */
+    async function resolveAgentsServerBuildAppPath(options) {
+        if (!isPathInsideNodeModules(options.sourceAppPath)) {
+            return options.sourceAppPath;
+        }
+        const sourceRuntimeRootPath = path.resolve(options.sourceAppPath, '..', '..');
+        const materializedRuntimeRootPath = resolvePromptbookTemporaryPath(process.cwd(), 'agents-server', 'runtime');
+        await synchronizeMaterializedAgentsServerRuntime({
+            materializedRuntimeRootPath,
+            nodeModulesPath: options.nodeModulesPath,
+            sourceAppPath: options.sourceAppPath,
+            sourceRuntimeRootPath,
+        });
+        return path.join(materializedRuntimeRootPath, 'apps', 'agents-server');
+    }
+    /**
+     * Copies the bundled runtime into the launch project when the original app lives under `node_modules`.
+     */
+    async function synchronizeMaterializedAgentsServerRuntime(options) {
+        const sourceFingerprint = await createAgentsServerBuildSourceFingerprint(options.sourceAppPath);
+        const runtimeCache = await readAgentsServerMaterializedRuntimeCache(options.materializedRuntimeRootPath);
+        const isRuntimeCurrent = (runtimeCache === null || runtimeCache === void 0 ? void 0 : runtimeCache.version) === AGENTS_SERVER_BUILD_CACHE_VERSION &&
+            runtimeCache.sourceFingerprint === sourceFingerprint &&
+            (await isAgentsServerAppPath(path.join(options.materializedRuntimeRootPath, 'apps', 'agents-server')));
+        if (!isRuntimeCurrent) {
+            await promises.rm(options.materializedRuntimeRootPath, { recursive: true, force: true });
+            await promises.mkdir(options.materializedRuntimeRootPath, { recursive: true });
+            for (const relativeInputPath of AGENTS_SERVER_BUILD_INPUT_RELATIVE_PATHS) {
+                await copyAgentsServerRuntimePath({
+                    destinationPath: path.join(options.materializedRuntimeRootPath, relativeInputPath),
+                    sourcePath: path.join(options.sourceRuntimeRootPath, relativeInputPath),
+                });
+            }
+            await assertMaterializedAgentsServerAppExists(options.materializedRuntimeRootPath);
+            await writeAgentsServerMaterializedRuntimeCache(options.materializedRuntimeRootPath, sourceFingerprint);
+        }
+        await ensureMaterializedRuntimeNodeModulesLink({
+            materializedRuntimeRootPath: options.materializedRuntimeRootPath,
+            nodeModulesPath: options.nodeModulesPath,
+        });
+    }
+    /**
+     * Verifies that the materialized runtime contains a usable Next app before caching it.
+     */
+    async function assertMaterializedAgentsServerAppExists(materializedRuntimeRootPath) {
+        const materializedAppPath = path.join(materializedRuntimeRootPath, 'apps', 'agents-server');
+        if (await isAgentsServerAppPath(materializedAppPath)) {
+            return;
+        }
+        throw new NotAllowed(_spaceTrim.spaceTrim(`
+            Cannot prepare the bundled Agents Server runtime.
+
+            The materialized app path is missing required files:
+            \`${materializedAppPath}\`
+        `));
+    }
+    /**
+     * Copies one source path into the materialized runtime, skipping generated or private files.
+     */
+    async function copyAgentsServerRuntimePath(options) {
+        let sourceStats;
+        try {
+            sourceStats = await promises.stat(options.sourcePath);
+        }
+        catch (_a) {
+            return;
+        }
+        await promises.mkdir(path.dirname(options.destinationPath), { recursive: true });
+        if (sourceStats.isDirectory()) {
+            await promises.cp(options.sourcePath, options.destinationPath, {
+                recursive: true,
+                filter: (sourcePath) => shouldCopyAgentsServerRuntimePath(sourcePath, options.sourcePath),
+            });
+            return;
+        }
+        if (sourceStats.isFile() && shouldCopyAgentsServerRuntimePath(options.sourcePath, path.dirname(options.sourcePath))) {
+            await promises.cp(options.sourcePath, options.destinationPath);
+        }
+    }
+    /**
+     * Excludes build artifacts, dependency folders, private env files, and test sources.
+     */
+    function shouldCopyAgentsServerRuntimePath(sourcePath, sourceRootPath) {
+        const sourceRelativePath = path.relative(sourceRootPath, sourcePath).replace(/\\/gu, '/');
+        const sourcePathSegments = sourceRelativePath.split('/').filter(Boolean);
+        const sourceBasename = path.basename(sourcePath);
+        if (sourcePathSegments.some((sourcePathSegment) => AGENTS_SERVER_BUILD_INPUT_EXCLUDED_DIRECTORY_NAMES.has(sourcePathSegment))) {
+            return false;
+        }
+        if (sourceBasename.startsWith('.env')) {
+            return false;
+        }
+        return !AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN.test(sourceBasename);
+    }
+    /**
+     * Links the materialized runtime back to the package dependency tree used by the installed CLI.
+     */
+    async function ensureMaterializedRuntimeNodeModulesLink(options) {
+        const nodeModulesLinkPath = path.join(options.materializedRuntimeRootPath, NODE_MODULES_DIRECTORY_NAME);
+        try {
+            const existingLinkStats = await promises.lstat(nodeModulesLinkPath);
+            await promises.rm(nodeModulesLinkPath, {
+                force: true,
+                recursive: existingLinkStats.isDirectory() && !existingLinkStats.isSymbolicLink(),
+            });
+        }
+        catch (_a) {
+            // The link does not exist yet.
+        }
+        await promises.symlink(options.nodeModulesPath, nodeModulesLinkPath, process.platform === 'win32' ? 'junction' : 'dir');
+    }
+    /**
+     * Reads and validates materialized runtime metadata.
+     */
+    async function readAgentsServerMaterializedRuntimeCache(materializedRuntimeRootPath) {
+        try {
+            const serializedRuntimeCache = await promises.readFile(path.join(materializedRuntimeRootPath, AGENTS_SERVER_MATERIALIZED_RUNTIME_CACHE_FILENAME), 'utf-8');
+            const runtimeCache = JSON.parse(serializedRuntimeCache);
+            if (runtimeCache.version !== AGENTS_SERVER_BUILD_CACHE_VERSION ||
+                typeof runtimeCache.sourceFingerprint !== 'string') {
+                return undefined;
+            }
+            return runtimeCache;
+        }
+        catch (_a) {
+            return undefined;
+        }
+    }
+    /**
+     * Persists the source fingerprint used for the materialized runtime copy.
+     */
+    async function writeAgentsServerMaterializedRuntimeCache(materializedRuntimeRootPath, sourceFingerprint) {
+        const runtimeCache = {
+            version: AGENTS_SERVER_BUILD_CACHE_VERSION,
+            sourceFingerprint,
+        };
+        await promises.writeFile(path.join(materializedRuntimeRootPath, AGENTS_SERVER_MATERIALIZED_RUNTIME_CACHE_FILENAME), `${JSON.stringify(runtimeCache, null, 4)}\n`, 'utf-8');
+    }
     /**
      * Runs the finite Next production build used by local Agents Server commands.
      */
@@ -3347,6 +3538,41 @@
         var _a;
         return path.resolve(options.appPath, ((_a = options.environment) === null || _a === void 0 ? void 0 : _a.NEXT_DIST_DIR) || DEFAULT_AGENTS_SERVER_NEXT_DIST_DIRECTORY_NAME);
     }
+    /**
+     * Returns true when the app path points at the project-local materialized runtime.
+     */
+    function isAgentsServerAppPathMaterialized(appPath) {
+        const normalizedAppPath = appPath.replace(/\\/gu, '/');
+        const normalizedMaterializedRuntimePath = resolvePromptbookTemporaryPath(process.cwd(), 'agents-server', 'runtime').replace(/\\/gu, '/');
+        return normalizedAppPath.includes(normalizedMaterializedRuntimePath);
+    }
+    /**
+     * Returns true when one path is nested below a `node_modules` segment.
+     */
+    function isPathInsideNodeModules(path) {
+        return path.split(/[\\/]+/u).includes(NODE_MODULES_DIRECTORY_NAME);
+    }
+    /**
+     * Resolves the dependency root that contains the installed Next CLI.
+     */
+    function resolveNodeModulesPath(nextCliPath) {
+        const normalizedNextCliPath = nextCliPath.replace(/\\/gu, '/');
+        const marker = `/${NODE_MODULES_DIRECTORY_NAME}/next/`;
+        const markerIndex = normalizedNextCliPath.lastIndexOf(marker);
+        if (markerIndex === -1) {
+            return path.resolve(nextCliPath, '..', '..', '..');
+        }
+        return normalizedNextCliPath.slice(0, markerIndex + marker.length - '/next/'.length);
+    }
+    /**
+     * Prepends one dependency root to `NODE_PATH` while preserving any existing value.
+     */
+    function mergeNodePath(nodeModulesPath, nodePath) {
+        if (!nodePath) {
+            return nodeModulesPath;
+        }
+        return `${nodeModulesPath}${path.delimiter}${nodePath}`;
+    }
     /**
      * Returns true when one path exists as a regular file.
      */
@@ -35882,6 +36108,12 @@
      * @private internal constant of `ptbk agents-server`
      */
     const PTBK_AGENTS_SERVER_SQLITE_PATH_ENV = 'PTBK_AGENTS_SERVER_SQLITE_PATH';
+    /**
+     * Optional hostname used by the internal Next server.
+     *
+     * @private internal constant of `ptbk agents-server`
+     */
+    const PTBK_HOSTNAME_ENV = 'PTBK_HOSTNAME';
     /**
      * Entropy size for the local-only token shared by the CLI pump and the Next app.
      *
@@ -35913,7 +36145,7 @@
         };
         process.once('exit', processExitHandler);
         try {
-            const { nextCliPath } = await ensureAgentsServerBuild({
+            const buildArtifacts = await ensureAgentsServerBuild({
                 appPath: runtimePaths.appPath,
                 environment: childEnvironment,
                 isBuildForced: options.isBuildForced,
@@ -35933,17 +36165,22 @@
                     });
                 },
             });
+            const runtimeChildEnvironment = createAgentsServerRuntimeEnvironment(childEnvironment, buildArtifacts.nodeModulesPath);
+            const builtRuntimePaths = {
+                ...runtimePaths,
+                appPath: buildArtifacts.appPath,
+            };
             nextServerProcess = startNextServer({
-                nextCliPath,
+                nextCliPath: buildArtifacts.nextCliPath,
                 options,
-                runtimePaths,
-                childEnvironment,
+                runtimePaths: builtRuntimePaths,
+                childEnvironment: runtimeChildEnvironment,
                 logStreams,
                 state,
             });
             stopUserChatJobWorkerPump = startUserChatJobWorkerPump({
                 port: options.port,
-                environment: childEnvironment,
+                environment: runtimeChildEnvironment,
                 logStreams,
                 state,
             });
@@ -35969,6 +36206,8 @@
     }
     /**
      * Loads launch-directory `.env` values without overriding explicit process environment.
+     *
+     * @private internal utility of `ptbk agents-server`
      */
     function loadAgentsServerProjectEnvironment(launchWorkingDirectory) {
         dotenv__namespace.config({ path: path.join(launchWorkingDirectory, AGENTS_SERVER_PROJECT_ENV_FILE_NAME) });
@@ -35993,8 +36232,15 @@
      * Starts the production Next server and wires its logs into the foreground dashboard.
      */
     function startNextServer(options) {
+        var _a;
         logRunnerEvent(options.logStreams.runner, 'Starting the Agents Server Next process.');
-        const commandProcess = child_process.spawn(process.execPath, [options.nextCliPath, 'start', '--port', String(options.options.port)], {
+        const nextArguments = [options.nextCliPath, 'start', '--port', String(options.options.port)];
+        const hostname = (_a = options.childEnvironment[PTBK_HOSTNAME_ENV]) === null || _a === void 0 ? void 0 : _a.trim();
+        if (hostname) {
+            nextArguments.push('--hostname', hostname);
+            logRunnerEvent(options.logStreams.runner, `Binding Agents Server Next process to ${hostname}.`);
+        }
+        const commandProcess = child_process.spawn(process.execPath, nextArguments, {
             cwd: options.runtimePaths.appPath,
             env: options.childEnvironment,
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -36326,6 +36572,7 @@
         command.description('Build the Agents Server Next app for later local startup');
         command.action(handleActionErrors(async () => {
             console.info(colors__default["default"].gray('Building Promptbook Agents Server.'));
+            loadAgentsServerProjectEnvironment(process.cwd());
             await ensureAgentsServerBuild({ isBuildForced: true });
         }));
     }
@@ -67358,6 +67605,38 @@
      * Global source-of-truth table for server routing and migration targeting.
      */
     const SERVER_REGISTRY_TABLE_NAME = '_Server';
+    /**
+     * Environment variable with comma-separated standalone server domains.
+     */
+    const SERVERS_ENV_NAME = 'SERVERS';
+    /**
+     * Stable timestamp used by virtual server records derived from environment variables.
+     */
+    const ENVIRONMENT_SERVER_TIMESTAMP = '1970-01-01T00:00:00.000Z';
+    /**
+     * Loads virtual server records from the comma-separated `SERVERS` environment variable.
+     *
+     * @returns Server records with deterministic table prefixes derived from normalized domains.
+     */
+    function listEnvironmentRegisteredServers() {
+        const rawServers = process.env[SERVERS_ENV_NAME];
+        if (!rawServers) {
+            return [];
+        }
+        const normalizedDomains = uniqueStrings$1(rawServers
+            .split(',')
+            .map((server) => normalizeServerDomain(server))
+            .filter((server) => Boolean(server)));
+        return normalizedDomains.map((domain, index) => ({
+            id: -(index + 1),
+            name: domain,
+            environment: SERVER_ENVIRONMENT.PRODUCTION,
+            domain,
+            tablePrefix: buildEnvironmentServerTablePrefix(domain),
+            createdAt: ENVIRONMENT_SERVER_TIMESTAMP,
+            updatedAt: ENVIRONMENT_SERVER_TIMESTAMP,
+        }));
+    }
     /**
      * Normalizes one raw `_Server` row and validates required fields.
      *
@@ -67478,6 +67757,39 @@
     function isDefaultPortForProtocol(protocol, port) {
         return (protocol === 'http:' && port === '80') || (protocol === 'https:' && port === '443');
     }
+    /**
+     * Builds a deterministic table prefix from a normalized domain.
+     *
+     * @param domain - Normalized server domain.
+     * @returns Prefix such as `server_www_example_com_`.
+     */
+    function buildEnvironmentServerTablePrefix(domain) {
+        const prefixSuffix = domain
+            .toLowerCase()
+            .replace(/-/gu, '_dash_')
+            .replace(/\./gu, '_')
+            .replace(/:/gu, '_port_')
+            .replace(/[^a-z0-9_]/gu, '_')
+            .replace(/_+/gu, '_')
+            .replace(/^_+|_+$/gu, '');
+        return `server_${prefixSuffix}_`;
+    }
+    /**
+     * Deduplicates non-empty strings while preserving input order.
+     *
+     * @param values - Raw string values.
+     * @returns Unique non-empty strings.
+     */
+    function uniqueStrings$1(values) {
+        const uniqueValues = [];
+        for (const value of values) {
+            if (!value || uniqueValues.includes(value)) {
+                continue;
+            }
+            uniqueValues.push(value);
+        }
+        return uniqueValues;
+    }
 
     /**
      * SQL query used to load all registered servers in a deterministic order.
@@ -67836,7 +68148,7 @@
         const client = await createPostgresClient(connectionString);
         try {
             await client.connect();
-            const registeredServers = await listRegisteredServersFromDatabase(client);
+            const registeredServers = mergeRegisteredServers(await listRegisteredServersFromDatabase(client), listEnvironmentRegisteredServers());
             const hasExplicitDefaultPrefix = process.env[SUPABASE_TABLE_PREFIX_ENV_NAME] !== undefined;
             const configuredPrefixes = uniquePrefixes([
                 ...(hasExplicitDefaultPrefix
@@ -67997,6 +68309,25 @@
         }
         return result;
     }
+    /**
+     * Combines database and environment registry rows, keeping database rows authoritative.
+     *
+     * @param databaseServers - Persistent `_Server` rows.
+     * @param environmentServers - Virtual rows derived from `SERVERS`.
+     * @returns Merged rows without duplicate domains.
+     */
+    function mergeRegisteredServers(databaseServers, environmentServers) {
+        const seenDomains = new Set(databaseServers.map((server) => server.domain));
+        const mergedServers = [...databaseServers];
+        for (const environmentServer of environmentServers) {
+            if (seenDomains.has(environmentServer.domain)) {
+                continue;
+            }
+            mergedServers.push(environmentServer);
+            seenDomains.add(environmentServer.domain);
+        }
+        return mergedServers;
+    }
     /**
      * Creates one PostgreSQL client using the lazily loaded `pg` package.
      *