@promptbook/cli 0.112.0-87 → 0.112.0-89

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-87';
+export const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version = '0.112.0-89';
 
 /**
  * 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-88`).
  *
  * @generated
  */

package/src/versions.txt

@@ -1124,4 +1124,5 @@
 0.112.0-79
 0.112.0-81
 0.112.0-82
-0.112.0-87
+0.112.0-88
+0.112.0-89

package/umd/index.umd.js

@@ -60,7 +60,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-87';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-89';
     /**
      * 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.
      */
@@ -35913,7 +36139,7 @@
         };
         process.once('exit', processExitHandler);
         try {
-            const { nextCliPath } = await ensureAgentsServerBuild({
+            const buildArtifacts = await ensureAgentsServerBuild({
                 appPath: runtimePaths.appPath,
                 environment: childEnvironment,
                 isBuildForced: options.isBuildForced,
@@ -35933,17 +36159,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 +36200,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) });
@@ -36326,6 +36559,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 });
         }));
     }