@promptbook/node 0.114.0-1 → 0.114.0-3

package/README.md

@@ -562,26 +562,27 @@ ptbk coder verify
 | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------ | ---- | ----- | ------------------------------------------------------------------------ |
 | `ptbk coder init`                     | Creates `prompts/`, `prompts/done/`, the project-generic template files materialized in `prompts/templates/` (currently `common.md`), and a starter `AGENTS.md`; ensures `.env` contains `CODING_AGENT_GIT_NAME`, `CODING_AGENT_GIT_EMAIL`, and `CODING_AGENT_GIT_SIGNING_KEY`; adds helper coder scripts to `package.json`; ensures `.gitignore` contains `/.promptbook`; and configures `.vscode/settings.json` to save pasted prompt images into `prompts/screenshots/`. |
 | `ptbk coder generate-boilerplates`    | Creates new prompt markdown files with fresh emoji tags so you can quickly fill in coding tasks; `--template` accepts either a built-in alias or a markdown file path relative to the project root.                                                                                                                                                                                                                                                                         |
-| `ptbk coder run`                      | Picks the next ready prompt, appends optional context, runs it through the selected coding agent, can optionally verify each attempt with a shell test command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                                                                                                  |
+| `ptbk coder run`                      | Picks the next ready prompt, can run tests before coding to stop or repair pre-existing failures, appends optional context, runs it through the selected coding agent, can optionally verify each attempt with a shell test command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                             |
 | `ptbk coder find-refactor-candidates` | Scans the repository for oversized or overpacked files and writes prompt files for likely refactors; `--level <xlow                                                                                                                                                                                                                                                                                                                                                         | low | medium | high | xhigh | extreme>` ranges from a very benevolent scan to a very aggressive sweep. |
 | `ptbk coder verify`                   | Walks through completed prompts, archives truly finished work, and adds follow-up repair prompts for unfinished results.                                                                                                                                                                                                                                                                                                                                                    |
 
 #### Most useful `ptbk coder run` flags
 
-| Flag                       | Purpose                                                                                            |
-| -------------------------- | -------------------------------------------------------------------------------------------------- |
-| `--harness <name>`         | Selects the coding harness.                                                                        |
-| `--model <model>`          | Chooses the runner model; required for `openai-codex` and `gemini`, optional for `github-copilot`. |
-| `--context <text-or-file>` | Appends extra instructions inline or from a file like `AGENTS.md`.                                 |
-| `--test <command>`         | Runs a verification command after each prompt attempt and feeds failing output back for retries.   |
-| `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                       |
-| `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue. |
-| `--ignore-git-changes`     | Disables the clean-working-tree guard.                                                             |
-| `--priority <n>`           | Runs only prompts at or above the given priority.                                                  |
-| `--dry-run`                | Prints which prompts are ready instead of executing them.                                          |
-| `--allow-credits`          | Lets OpenAI Codex spend credits when required.                                                     |
-| `--auto-push`              | Pushes each successful coding-agent commit to the configured remote.                               |
-| `--auto-migrate`           | Runs testing-server database migrations after each successful prompt.                              |
+| Flag                       | Purpose                                                                                                                                                                                |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--harness <name>`         | Selects the coding harness.                                                                                                                                                            |
+| `--model <model>`          | Chooses the runner model; required for `openai-codex` and `gemini`, optional for `github-copilot`.                                                                                     |
+| `--context <text-or-file>` | Appends extra instructions inline or from a file like `AGENTS.md`.                                                                                                                     |
+| `--test <command>`         | Runs a verification command after each prompt attempt and feeds failing output back for retries.                                                                                       |
+| `--test-before <mode>`     | Runs tests before coding: `no` (default), `yes-and-fail` (stop with results), or `yes-and-fix` (create one repair prompt first); defaults to `npm test` when enabled without `--test`. |
+| `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                                                                                                           |
+| `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue.                                                                                     |
+| `--ignore-git-changes`     | Disables the clean-working-tree guard.                                                                                                                                                 |
+| `--priority <n>`           | Runs only prompts at or above the given priority.                                                                                                                                      |
+| `--dry-run`                | Prints which prompts are ready instead of executing them.                                                                                                                              |
+| `--allow-credits`          | Lets OpenAI Codex spend credits when required.                                                                                                                                         |
+| `--auto-push`              | Pushes each successful coding-agent commit to the configured remote.                                                                                                                   |
+| `--auto-migrate`           | Runs testing-server database migrations after each successful prompt.                                                                                                                  |
 
 #### Typical usage pattern
 

package/esm/index.es.js

@@ -3,14 +3,10 @@ import { unlink, mkdir, appendFile, writeFile, readFile, stat, access, constants
 import _spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
 import colors from 'colors';
 import { spawn } from 'child_process';
-import { fileSearchTool, tool, Agent as Agent$1, webSearchTool, run, setDefaultOpenAIClient, setDefaultOpenAIKey } from '@openai/agents';
 import { fileURLToPath } from 'url';
-import { Readability } from '@mozilla/readability';
-import { JSDOM } from 'jsdom';
 import CryptoJS from 'crypto-js';
 import hexEncoder from 'crypto-js/enc-hex';
 import showdown from 'showdown';
-import JSZip from 'jszip';
 import { forTime } from 'waitasecond';
 import * as dotenv from 'dotenv';
 import sha256 from 'crypto-js/sha256';
@@ -20,7 +16,6 @@ import moment from 'moment';
 import { lookup, extension } from 'mime-types';
 import papaparse from 'papaparse';
 import Bottleneck from 'bottleneck';
-import OpenAI from 'openai';
 
 // ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten
 /**
@@ -36,7 +31,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-1';
+const PROMPTBOOK_ENGINE_VERSION = '0.114.0-3';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -2936,6 +2931,13 @@ function toPosixPath(filePath) {
  * Environment variable read by the shell wrapper to tee live output into the temporary runtime log file.
  */
 const PTBK_CODER_LOG_FILE_ENV_NAME = 'PTBK_CODER_LOG_FILE';
+/**
+ * Log line which separates the raw script input from the raw script output of one execution section.
+ *
+ * Readers of a runtime log split on this marker to look only at what the harness really produced,
+ * without the generated script and the prompt it embeds.
+ */
+const SCRIPT_EXECUTION_LOG_RAW_OUTPUT_MARKER = '--- raw output ---';
 /**
  * Small bash wrapper that preserves stdout/stderr streams while teeing both into the runtime log file.
  */
@@ -2971,7 +2973,7 @@ async function appendScriptExecutionLogStart({ scriptPath, scriptContent, logPat
             --- raw input ---
             ${block(normalizedInput)}
 
-            --- raw output ---
+            ${SCRIPT_EXECUTION_LOG_RAW_OUTPUT_MARKER}
         `);
     await appendFile(logPath, `${logSection}\n`, 'utf-8');
 }
@@ -4314,6 +4316,7 @@ function buildCodexScript(options) {
         `    -c model_reasoning_effort="${thinkingLevel}" \\`,
         `    --ask-for-approval ${options.askForApproval} \\`,
         `    exec --model ${options.model} \\`,
+        ...(options.isMachineReadableProgressEnabled ? ['    --json \\'] : []),
         '    --local-provider none \\',
         `    --sandbox ${options.sandbox} \\`,
         `    -C ${projectPath} \\`,
@@ -4630,6 +4633,10 @@ function matchesAnyPattern(text, patterns) {
  * Output line that marks finished Codex usage summary.
  */
 const CODEX_COMPLETION_LINE = /^\s*tokens used\b/i;
+/**
+ * Output line that marks the completed Codex turn in JSONL output mode.
+ */
+const CODEX_JSON_COMPLETION_LINE = /^\s*\{"type":"turn\.(?:completed|failed)"/u;
 /**
  * Idle timeout after completion marker to capture trailing output.
  */
@@ -4706,6 +4713,7 @@ class OpenAiCodexRunner {
             sandbox: this.options.sandbox,
             askForApproval: this.options.askForApproval,
             allowCredits: this.options.allowCredits,
+            isMachineReadableProgressEnabled: this.options.isMachineReadableProgressEnabled,
             codexCommand: this.options.codexCommand,
         });
         for (let retryIndex = 0;; retryIndex++) {
@@ -4720,7 +4728,9 @@ class OpenAiCodexRunner {
                 const output = await $runGoScriptUntilMarkerIdle({
                     scriptPath: options.scriptPath,
                     scriptContent,
-                    completionLineMatcher: CODEX_COMPLETION_LINE,
+                    completionLineMatcher: this.options.isMachineReadableProgressEnabled
+                        ? CODEX_JSON_COMPLETION_LINE
+                        : CODEX_COMPLETION_LINE,
                     idleTimeoutMs: CODEX_COMPLETION_IDLE_MS,
                     logPath: options.logPath,
                     shouldPrintLiveOutput: options.shouldPrintLiveOutput,
@@ -4970,6 +4980,7 @@ function createOpenAiCodexRunnerResolution(options) {
         sandbox: 'danger-full-access',
         askForApproval: 'never',
         allowCredits: options.allowCredits,
+        isMachineReadableProgressEnabled: options.isMachineReadableProgressEnabled,
     });
     if (!options.allowCredits && options.isVerbose === true) {
         console.info(colors.gray('OpenAI Codex credit spending is disabled. Use `--allow-credits` to explicitly opt in.'));
@@ -32894,6 +32905,41 @@ function buildToolInvocationScript(options) {
     `;
 }
 
+/**
+ * Creates a loader which imports one module on the first call and reuses the very same module afterwards
+ *
+ * Note: [🐌] Heavy third-party dependencies are imported lazily to keep the startup of the Promptbook CLI fast.
+ *       A statically imported dependency is loaded every single time the bundle is loaded, even when the running
+ *       command never touches it. A lazily imported dependency is loaded only when the feature is really used.
+ *
+ * @example
+ * const loadJsdomModule = createLazyModuleLoader(() => import('jsdom'));
+ * const { JSDOM } = await loadJsdomModule();
+ *
+ * @private internal utility of Promptbook
+ */
+function createLazyModuleLoader(importModule) {
+    let importedModulePromise = null;
+    return function loadModule() {
+        if (importedModulePromise === null) {
+            importedModulePromise = importModule();
+        }
+        return importedModulePromise;
+    };
+}
+// Note: [🐌] Do not convert the lazy `import(...)` calls back to static `import` statements, it would bring back the
+//       slow startup of the `ptbk` CLI utility
+
+/**
+ * Loads the OpenAI AgentKit SDK (`@openai/agents`) on demand
+ *
+ * Note: [🐌] The AgentKit SDK is one of the heaviest dependencies of Promptbook, loading it eagerly would slow down
+ *       every single run of the `ptbk` CLI utility even when no AgentKit agent is used
+ *
+ * @private internal utility of `@promptbook/openai`
+ */
+const loadOpenAiAgentsModule = createLazyModuleLoader(() => import('@openai/agents'));
+
 /**
  * Constant for default model used for nested DeepSearch tool invocations.
  */
@@ -32947,8 +32993,9 @@ class OpenAiAgentKitExecutionToolsToolBuilder {
     /**
      * Builds the tool list for AgentKit, including hosted file search when applicable.
      */
-    buildAgentKitTools(options) {
+    async buildAgentKitTools(options) {
         const { tools, vectorStoreId } = options;
+        const { fileSearchTool, tool: agentKitTool } = await loadOpenAiAgentsModule();
         const agentKitTools = [];
         if (vectorStoreId) {
             agentKitTools.push(fileSearchTool(vectorStoreId));
@@ -32959,11 +33006,11 @@ class OpenAiAgentKitExecutionToolsToolBuilder {
         let scriptTools = null;
         for (const toolDefinition of tools) {
             if (this.isDeepSearchToolDefinition(toolDefinition)) {
-                agentKitTools.push(this.createDeepSearchAgentKitTool(toolDefinition));
+                agentKitTools.push(await this.createDeepSearchAgentKitTool(toolDefinition));
                 continue;
             }
             scriptTools !== null && scriptTools !== void 0 ? scriptTools : (scriptTools = this.resolveScriptTools());
-            agentKitTools.push(tool({
+            agentKitTools.push(agentKitTool({
                 name: toolDefinition.name,
                 description: toolDefinition.description,
                 parameters: this.normalizeAgentKitToolParameters(toolDefinition.parameters),
@@ -33170,8 +33217,9 @@ class OpenAiAgentKitExecutionToolsToolBuilder {
     /**
      * Creates the native Agent SDK tool used for `USE DEEPSEARCH`.
      */
-    createDeepSearchAgentKitTool(toolDefinition) {
-        const deepSearchAgent = new Agent$1({
+    async createDeepSearchAgentKitTool(toolDefinition) {
+        const { Agent: AgentFromKit, webSearchTool } = await loadOpenAiAgentsModule();
+        const deepSearchAgent = new AgentFromKit({
             name: 'DeepSearch',
             model: DEFAULT_DEEP_SEARCH_MODEL_NAME,
             instructions: this.createDeepSearchAgentInstructions(toolDefinition.description),
@@ -33739,6 +33787,14 @@ class OpenAiCompatibleNonChatPromptCaller {
     }
 }
 
+/**
+ * Loads the OpenAI SDK (`openai`) on demand
+ *
+ * Note: [🐌] Loaded lazily to keep the startup of the `ptbk` CLI utility fast
+ *
+ * @private internal utility of `OpenAiCompatibleRequestManager`
+ */
+const loadOpenAiModule = createLazyModuleLoader(() => import('openai'));
 /**
  * Manages OpenAI-compatible client creation plus shared retry and rate-limit behavior.
  *
@@ -33765,6 +33821,7 @@ class OpenAiCompatibleRequestManager {
                 timeout: API_REQUEST_TIMEOUT,
                 maxRetries: CONNECTION_RETRIES_LIMIT,
             };
+            const { default: OpenAI } = await loadOpenAiModule();
             this.client = new OpenAI(enhancedOptions);
         }
         return this.client;
@@ -36111,7 +36168,23 @@ function createShowdownConverter() {
     });
 }
 
-// TODO: [🏳‍🌈] Finally take pick of .json vs .ts
+/**
+ * Loads `jsdom` on demand
+ *
+ * Note: [🐌] `jsdom` is by far the heaviest dependency of Promptbook, loading it eagerly would slow down every single
+ *       run of the `ptbk` CLI utility even when no website is scraped
+ *
+ * @private internal utility of `WebsiteScraper`
+ */
+const loadJsdomModule = createLazyModuleLoader(() => import('jsdom'));
+/**
+ * Loads `@mozilla/readability` on demand
+ *
+ * Note: [🐌] Loaded lazily to keep the startup of the `ptbk` CLI utility fast
+ *
+ * @private internal utility of `WebsiteScraper`
+ */
+const loadReadabilityModule = createLazyModuleLoader(() => import('@mozilla/readability'));
 /**
  * Scraper for websites
  *
@@ -36147,6 +36220,7 @@ class WebsiteScraper {
         if (this.tools.fs === undefined) {
             throw new EnvironmentMismatchError('Can not scrape websites without filesystem tools');
         }
+        const [{ JSDOM }, { Readability }] = await Promise.all([loadJsdomModule(), loadReadabilityModule()]);
         const jsdom = new JSDOM(await source.asText(), {
             url: source.url,
         });
@@ -39410,6 +39484,7 @@ class LiteAgent {
         }
         const preparedAgent = await this.prepareAgent();
         (_a = preparedAgent.toolBuilder) === null || _a === void 0 ? void 0 : _a.clearRunState();
+        const { run } = await loadOpenAiAgentsModule();
         const result = await run(preparedAgent.agent, createLiteAgentPromptText(normalizedMessage, options.context, preparedAgent.modelRequirements.promptSuffix), options.signal ? { signal: options.signal } : undefined);
         return formatLiteAgentOutput(result.finalOutput);
     }
@@ -39449,6 +39524,7 @@ class LiteAgent {
             userId: this.options.userId,
         });
         const client = await runtime.getClient();
+        const { Agent: AgentFromKit, fileSearchTool, setDefaultOpenAIClient, setDefaultOpenAIKey, } = await loadOpenAiAgentsModule();
         setDefaultOpenAIClient(client);
         if (this.options.apiKey) {
             setDefaultOpenAIKey(this.options.apiKey);
@@ -39469,9 +39545,9 @@ class LiteAgent {
                 agentKitModelName: resolvedModelName,
             })
             : null;
-        const agentTools = (toolBuilder === null || toolBuilder === void 0 ? void 0 : toolBuilder.buildAgentKitTools({
+        const agentTools = (await (toolBuilder === null || toolBuilder === void 0 ? void 0 : toolBuilder.buildAgentKitTools({
             tools: modelRequirements.tools ? [...modelRequirements.tools] : undefined,
-        })) || [];
+        }))) || [];
         const normalizedKnowledgeSources = await normalizeLiteAgentKnowledgeSources(modelRequirements.knowledgeSources || [], resolvedSource.sourceDirectoryPath);
         if (normalizedKnowledgeSources.length > 0) {
             const vectorStore = await runtime.createHostedKnowledgeVectorStore({
@@ -39481,7 +39557,7 @@ class LiteAgent {
             agentTools.unshift(fileSearchTool(vectorStore.vectorStoreId));
         }
         return {
-            agent: new Agent$1({
+            agent: new AgentFromKit({
                 name: resolvedSource.agentName,
                 model: resolvedModelName,
                 instructions: modelRequirements.systemMessage || 'You are a helpful assistant.',
@@ -39690,6 +39766,15 @@ function resolveLiteAgentKnowledgeSourceMimeType(fileName) {
     }
 }
 
+/**
+ * Loads the ZIP archive library (`jszip`) on demand
+ *
+ * Note: [🐌] Loaded lazily to keep the startup of the `ptbk` CLI utility fast
+ *
+ * @private internal utility of `loadArchive` and `saveArchive`
+ */
+const loadJsZipModule = createLazyModuleLoader(() => import('jszip'));
+
 /**
  * Loads the books from the archive file with `.bookc` extension
  *
@@ -39704,6 +39789,7 @@ async function loadArchive(filePath, fs) {
         throw new UnexpectedError(`Archive file must have '.bookc' extension`);
     }
     const data = await fs.readFile(filePath);
+    const { default: JSZip } = await loadJsZipModule();
     const archive = await JSZip.loadAsync(data);
     const indexFile = archive.file('index.book.json');
     if (!indexFile) {
@@ -46076,8 +46162,9 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
                 vectorStoreId,
             });
         }
-        const agentKitTools = this.buildAgentKitTools({ tools, vectorStoreId });
-        const openAiAgentKitAgent = new Agent$1({
+        const { Agent: AgentFromKit } = await loadOpenAiAgentsModule();
+        const agentKitTools = await this.buildAgentKitTools({ tools, vectorStoreId });
+        const openAiAgentKitAgent = new AgentFromKit({
             name,
             model: this.agentKitModelName,
             instructions: instructions || 'You are a helpful assistant.',
@@ -46122,6 +46209,7 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
             agentName: agentForRun.name,
             input: inputItems,
         };
+        const { run } = await loadOpenAiAgentsModule();
         const streamResult = await run(agentForRun, inputItems, {
             stream: true,
             maxTurns: 200,
@@ -46264,6 +46352,7 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
      * Ensures the AgentKit SDK is wired to the OpenAI client and API key.
      */
     async ensureAgentKitDefaults() {
+        const { setDefaultOpenAIClient, setDefaultOpenAIKey } = await loadOpenAiAgentsModule();
         const client = await this.getClient();
         setDefaultOpenAIClient(client);
         const apiKey = this.agentKitOptions.apiKey;