@promptbook/cli 0.112.0-88 → 0.112.0-90

package/esm/index.es.js

@@ -1,8 +1,8 @@
 import colors from 'colors';
 import commander, { Option } from 'commander';
 import _spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
-import { writeFile, stat, mkdir, readFile, readdir, unlink, appendFile, rm, rename, access, constants, watch, rmdir } from 'fs/promises';
-import { join, resolve, basename, relative, isAbsolute, dirname, extname } from 'path';
+import { writeFile, stat, mkdir, readFile, rm, cp, lstat, symlink, readdir, unlink, appendFile, rename, access, constants, watch, rmdir } from 'fs/promises';
+import { join, resolve, dirname, relative, basename, delimiter, isAbsolute, extname } from 'path';
 import { spawn } from 'child_process';
 import { createHash, randomBytes } from 'crypto';
 import * as fs from 'fs';
@@ -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-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
@@ -3102,6 +3102,31 @@ 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';
+/**
+ * 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.
  *
@@ -3146,26 +3171,33 @@ const AGENTS_SERVER_BUILD_INPUT_TEST_FILE_PATTERN = /\.(?:spec|test)\.[jt]sx?$/i
  */
 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.
@@ -3221,6 +3253,165 @@ async function resolveAgentsServerAppPath() {
             ${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 = resolve(options.sourceAppPath, '..', '..');
+    const materializedRuntimeRootPath = resolvePromptbookTemporaryPath(process.cwd(), 'agents-server', 'runtime');
+    await synchronizeMaterializedAgentsServerRuntime({
+        materializedRuntimeRootPath,
+        nodeModulesPath: options.nodeModulesPath,
+        sourceAppPath: options.sourceAppPath,
+        sourceRuntimeRootPath,
+    });
+    return 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(join(options.materializedRuntimeRootPath, 'apps', 'agents-server')));
+    if (!isRuntimeCurrent) {
+        await rm(options.materializedRuntimeRootPath, { recursive: true, force: true });
+        await mkdir(options.materializedRuntimeRootPath, { recursive: true });
+        for (const relativeInputPath of AGENTS_SERVER_BUILD_INPUT_RELATIVE_PATHS) {
+            await copyAgentsServerRuntimePath({
+                destinationPath: join(options.materializedRuntimeRootPath, relativeInputPath),
+                sourcePath: 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 = join(materializedRuntimeRootPath, 'apps', 'agents-server');
+    if (await isAgentsServerAppPath(materializedAppPath)) {
+        return;
+    }
+    throw new NotAllowed(spaceTrim$1(`
+            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 stat(options.sourcePath);
+    }
+    catch (_a) {
+        return;
+    }
+    await mkdir(dirname(options.destinationPath), { recursive: true });
+    if (sourceStats.isDirectory()) {
+        await cp(options.sourcePath, options.destinationPath, {
+            recursive: true,
+            filter: (sourcePath) => shouldCopyAgentsServerRuntimePath(sourcePath, options.sourcePath),
+        });
+        return;
+    }
+    if (sourceStats.isFile() && shouldCopyAgentsServerRuntimePath(options.sourcePath, dirname(options.sourcePath))) {
+        await cp(options.sourcePath, options.destinationPath);
+    }
+}
+/**
+ * Excludes build artifacts, dependency folders, private env files, and test sources.
+ */
+function shouldCopyAgentsServerRuntimePath(sourcePath, sourceRootPath) {
+    const sourceRelativePath = relative(sourceRootPath, sourcePath).replace(/\\/gu, '/');
+    const sourcePathSegments = sourceRelativePath.split('/').filter(Boolean);
+    const sourceBasename = 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 = join(options.materializedRuntimeRootPath, NODE_MODULES_DIRECTORY_NAME);
+    try {
+        const existingLinkStats = await lstat(nodeModulesLinkPath);
+        await rm(nodeModulesLinkPath, {
+            force: true,
+            recursive: existingLinkStats.isDirectory() && !existingLinkStats.isSymbolicLink(),
+        });
+    }
+    catch (_a) {
+        // The link does not exist yet.
+    }
+    await symlink(options.nodeModulesPath, nodeModulesLinkPath, process.platform === 'win32' ? 'junction' : 'dir');
+}
+/**
+ * Reads and validates materialized runtime metadata.
+ */
+async function readAgentsServerMaterializedRuntimeCache(materializedRuntimeRootPath) {
+    try {
+        const serializedRuntimeCache = await readFile(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 writeFile(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.
  */
@@ -3345,6 +3536,41 @@ function resolveAgentsServerBuildOutputPath(options) {
     var _a;
     return 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 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}${delimiter}${nodePath}`;
+}
 /**
  * Returns true when one path exists as a regular file.
  */
@@ -35880,6 +36106,12 @@ const PTBK_AGENTS_SERVER_DATABASE_ENV = 'PTBK_AGENTS_SERVER_DATABASE';
  * @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.
  *
@@ -35911,7 +36143,7 @@ async function startAgentsServer(options) {
     };
     process.once('exit', processExitHandler);
     try {
-        const { nextCliPath } = await ensureAgentsServerBuild({
+        const buildArtifacts = await ensureAgentsServerBuild({
             appPath: runtimePaths.appPath,
             environment: childEnvironment,
             isBuildForced: options.isBuildForced,
@@ -35931,17 +36163,22 @@ async function startAgentsServer(options) {
                 });
             },
         });
+        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,
         });
@@ -35967,6 +36204,8 @@ async function startAgentsServer(options) {
 }
 /**
  * Loads launch-directory `.env` values without overriding explicit process environment.
+ *
+ * @private internal utility of `ptbk agents-server`
  */
 function loadAgentsServerProjectEnvironment(launchWorkingDirectory) {
     dotenv.config({ path: join(launchWorkingDirectory, AGENTS_SERVER_PROJECT_ENV_FILE_NAME) });
@@ -35991,8 +36230,15 @@ async function resolveAgentsServerRuntimePaths() {
  * 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 = 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 = spawn(process.execPath, nextArguments, {
         cwd: options.runtimePaths.appPath,
         env: options.childEnvironment,
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -36324,6 +36570,7 @@ function $initializeAgentsServerBuildCommand(program) {
     command.description('Build the Agents Server Next app for later local startup');
     command.action(handleActionErrors(async () => {
         console.info(colors.gray('Building Promptbook Agents Server.'));
+        loadAgentsServerProjectEnvironment(process.cwd());
         await ensureAgentsServerBuild({ isBuildForced: true });
     }));
 }
@@ -67356,6 +67603,38 @@ const SERVER_ENVIRONMENT = {
  * 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.
  *
@@ -67476,6 +67755,39 @@ function hasHttpProtocol(value) {
 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.
@@ -67834,7 +68146,7 @@ async function resolveDatabaseMigrationRuntimeConfiguration(logger = console) {
     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
@@ -67995,6 +68307,25 @@ function uniquePrefixes(prefixes) {
     }
     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.
  *