@promptbook/core/esm/index.es.js

It's time for a paradigm shift. The future of software in plain English, French or Latin

import spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
import { format } from 'prettier';
import parserHtml from 'prettier/parser-html';
import { Subject } from 'rxjs';
import { randomBytes } from 'crypto';
import { forTime } from 'waitasecond';
import { parse, unparse } from 'papaparse';
import hexEncoder from 'crypto-js/enc-hex';
import sha256 from 'crypto-js/sha256';
import { basename, join, dirname } from 'path';
import { SHA256 } from 'crypto-js';
import { lookup, extension } from 'mime-types';
import moment from 'moment';
import colors from 'colors';

// ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten
/**
 * The version of the Book language
 *
 * @generated
 * @see https://github.com/webgptorg/book
 */
const BOOK_LANGUAGE_VERSION = '1.0.0';
/**
 * The version of the Promptbook engine
 *
 * @generated
 * @see https://github.com/webgptorg/promptbook
 */
const PROMPTBOOK_ENGINE_VERSION = '0.89.0-16';
/**
 * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
 * Note: [💞] Ignore a discrepancy between file name and entity name
 */

/**
 * Converts PipelineCollection to serialized JSON
 *
 * Note: Functions `collectionToJson` and `createCollectionFromJson` are complementary
 *
 * @public exported from `@promptbook/core`
 */
async function collectionToJson(collection) {
    const pipelineUrls = await collection.listPipelines();
    const promptbooks = await Promise.all(pipelineUrls.map((url) => collection.getPipelineByUrl(url)));
    return promptbooks;
}
/**
 * TODO: [🧠] Maybe clear `sourceFile` or clear when exposing through API or remote server
 */

/**
 * Checks if value is valid email
 *
 * @public exported from `@promptbook/utils`
 */
function isValidEmail(email) {
    if (typeof email !== 'string') {
        return false;
    }
    if (email.split('\n').length > 1) {
        return false;
    }
    return /^.+@.+\..+$/.test(email);
}

/**
 * Tests if given string is valid URL.
 *
 * Note: This does not check if the file exists only if the path is valid
 * @public exported from `@promptbook/utils`
 */
function isValidFilePath(filename) {
    if (typeof filename !== 'string') {
        return false;
    }
    if (filename.split('\n').length > 1) {
        return false;
    }
    if (filename.split(' ').length >
        5 /* <- TODO: [🧠][🈷] Make some better non-arbitrary way how to distinct filenames from informational texts */) {
        return false;
    }
    const filenameSlashes = filename.split('\\').join('/');
    // Absolute Unix path: /hello.txt
    if (/^(\/)/i.test(filenameSlashes)) {
        // console.log(filename, 'Absolute Unix path: /hello.txt');
        return true;
    }
    // Absolute Windows path: /hello.txt
    if (/^([A-Z]{1,2}:\/?)\//i.test(filenameSlashes)) {
        // console.log(filename, 'Absolute Windows path: /hello.txt');
        return true;
    }
    // Relative path: ./hello.txt
    if (/^(\.\.?\/)+/i.test(filenameSlashes)) {
        // console.log(filename, 'Relative path: ./hello.txt');
        return true;
    }
    // Allow paths like foo/hello
    if (/^[^/]+\/[^/]+/i.test(filenameSlashes)) {
        // console.log(filename, 'Allow paths like foo/hello');
        return true;
    }
    // Allow paths like hello.book
    if (/^[^/]+\.[^/]+$/i.test(filenameSlashes)) {
        // console.log(filename, 'Allow paths like hello.book');
        return true;
    }
    return false;
}
/**
 * TODO: [🍏] Implement for MacOs
 */

/**
 * Tests if given string is valid URL.
 *
 * Note: Dataurl are considered perfectly valid.
 * Note: There are two simmilar functions:
 * - `isValidUrl` which tests any URL
 * - `isValidPipelineUrl` *(this one)* which tests just promptbook URL
 *
 * @public exported from `@promptbook/utils`
 */
function isValidUrl(url) {
    if (typeof url !== 'string') {
        return false;
    }
    try {
        if (url.startsWith('blob:')) {
            url = url.replace(/^blob:/, '');
        }
        const urlObject = new URL(url /* because fail is handled */);
        if (!['http:', 'https:', 'data:'].includes(urlObject.protocol)) {
            return false;
        }
        return true;
    }
    catch (error) {
        return false;
    }
}

/**
 * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
 *
 * @public exported from `@promptbook/core`
 */
class ParseError extends Error {
    constructor(message) {
        super(message);
        this.name = 'ParseError';
        Object.setPrototypeOf(this, ParseError.prototype);
    }
}
/**
 * TODO: Maybe split `ParseError` and `ApplyError`
 */

/**
 * Returns the same value that is passed as argument.
 * No side effects.
 *
 * Note: It can be usefull for:
 *
 * 1) Leveling indentation
 * 2) Putting always-true or always-false conditions without getting eslint errors
 *
 * @param value any values
 * @returns the same values
 * @private within the repository
 */
function just(value) {
    if (value === undefined) {
        return undefined;
    }
    return value;
}

/**
 * Warning message for the generated sections and files files
 *
 * @private within the repository
 */
const GENERATOR_WARNING = `⚠️ WARNING: This code has been generated so that any manual changes will be overwritten`;
/**
 * Name for the Promptbook
 *
 * TODO: [🗽] Unite branding and make single place for it
 *
 * @public exported from `@promptbook/core`
 */
const NAME = `Promptbook`;
/**
 * Email of the responsible person
 *
 * @public exported from `@promptbook/core`
 */
const ADMIN_EMAIL = 'pavol@ptbk.io';
/**
 * Name of the responsible person for the Promptbook on GitHub
 *
 * @public exported from `@promptbook/core`
 */
const ADMIN_GITHUB_NAME = 'hejny';
/**
 * Claim for the Promptbook
 *
 * TODO: [🗽] Unite branding and make single place for it
 *
 * @public exported from `@promptbook/core`
 */
const CLAIM = `It's time for a paradigm shift. The future of software in plain English, French or Latin`;
//            <- TODO: [🐊] Pick the best claim
/**
 * When the title is not provided, the default title is used
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_BOOK_TITLE = `✨ Untitled Book`;
/**
 * When the title of task is not provided, the default title is used
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_TASK_TITLE = `Task`;
/**
 * When the title of the prompt task is not provided, the default title is used
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_PROMPT_TASK_TITLE = `Prompt`;
/**
 * When the pipeline is flat and no name of return parameter is provided, this name is used
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_BOOK_OUTPUT_PARAMETER_NAME = 'result';
/**
 * Maximum file size limit
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024; // 100MB
// <- TODO: [🧠] Better system for generator warnings - not always "code" and "by `@promptbook/cli`"
/**
 * The maximum number of iterations for a loops
 *
 * @private within the repository - too low-level in comparison with other `MAX_...`
 */
const LOOP_LIMIT = 1000;
/**
 * Strings to represent various values in the context of parameter values
 *
 * @public exported from `@promptbook/utils`
 */
const VALUE_STRINGS = {
    empty: '(nothing; empty string)',
    null: '(no value; null)',
    undefined: '(unknown value; undefined)',
    nan: '(not a number; NaN)',
    infinity: '(infinity; ∞)',
    negativeInfinity: '(negative infinity; -∞)',
    unserializable: '(unserializable value)',
    circular: '(circular JSON)',
};
/**
 * Small number limit
 *
 * @public exported from `@promptbook/utils`
 */
const SMALL_NUMBER = 0.001;
/**
 * Short time interval to prevent race conditions in milliseconds
 *
 * @private within the repository - too low-level in comparison with other `MAX_...`
 */
const IMMEDIATE_TIME = 10;
/**
 * The maximum length of the (generated) filename
 *
 * @public exported from `@promptbook/core`
 */
const MAX_FILENAME_LENGTH = 30;
/**
 * Strategy for caching the intermediate results for knowledge sources
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_INTERMEDIATE_FILES_STRATEGY = 'HIDE_AND_KEEP';
//                                                     <- TODO: [😡] Change to 'VISIBLE'
/**
 * The maximum number of (LLM) tasks running in parallel
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_MAX_PARALLEL_COUNT = 5; // <- TODO: [🤹‍♂️]
/**
 * The maximum number of attempts to execute LLM task before giving up
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_MAX_EXECUTION_ATTEMPTS = 10; // <- TODO: [🤹‍♂️]
/**
 * @@@
 * TODO: [🐝][main] !!3 Use
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_MAX_KNOWLEDGE_SOURCES_SCRAPING_DEPTH = 3;
/**
 * @@@
 * TODO: [🐝][main] !!3 Use
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_MAX_KNOWLEDGE_SOURCES_SCRAPING_TOTAL = 200;
/**
 * Where to store your books
 * This is kind of a "src" for your books
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_BOOKS_DIRNAME = './books';
// <- TODO: [🕝] Make also `BOOKS_DIRNAME_ALTERNATIVES`
// TODO: Just `.promptbook` in config, hardcode subfolders like `download-cache` or `execution-cache`
/**
 * Where to store the temporary downloads
 *
 * Note: When the folder does not exist, it is created recursively
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_DOWNLOAD_CACHE_DIRNAME = './.promptbook/download-cache';
/**
 * Where to store the cache of executions for promptbook CLI
 *
 * Note: When the folder does not exist, it is created recursively
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_EXECUTION_CACHE_DIRNAME = './.promptbook/execution-cache';
/**
 * Where to store the scrape cache
 *
 * Note: When the folder does not exist, it is created recursively
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_SCRAPE_CACHE_DIRNAME = './.promptbook/scrape-cache';
/**
 * Id of application for the CLI when using remote server
 *
 * @public exported from `@promptbook/core`
 */
const CLI_APP_ID = 'cli';
/**
 * Id of application for the playground
 *
 * @public exported from `@promptbook/core`
 */
const PLAYGROUND_APP_ID = 'playground';
/*
TODO: [🌃]
/**
 * Id of application for the wizzard when using remote server
 *
 * @public exported from `@promptbook/core`
 * /
ex-port const WIZZARD_APP_ID: string_app_id = 'wizzard';
*/
/**
 * The name of the builded pipeline collection made by CLI `ptbk make` and for lookup in `createCollectionFromDirectory`
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_PIPELINE_COLLECTION_BASE_FILENAME = `index`;
/**
 * The thresholds for the relative time in the `moment` NPM package.
 *
 * @see https://momentjscom.readthedocs.io/en/latest/moment/07-customization/13-relative-time-threshold/
 * @private within the repository - too low-level in comparison with other constants
 */
const MOMENT_ARG_THRESHOLDS = {
    ss: 3, // <- least number of seconds to be counted in seconds, minus 1. Must be set after setting the `s` unit or without setting the `s` unit.
};
/**
 * Available remote servers for the Promptbook
 *
 * @public exported from `@promptbook/core`
 */
const REMOTE_SERVER_URLS = [
    'https://s1.ptbk.io/promptbook',
    'https://api.pavolhejny.com/promptbook',
];
/**
 * Default remote server URL for the Promptbook
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_REMOTE_SERVER_URL = REMOTE_SERVER_URLS[0];
// <- TODO: [🧜‍♂️]
/**
 * @@@
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_CSV_SETTINGS = Object.freeze({
    delimiter: ',',
    quoteChar: '"',
    newline: '\n',
    skipEmptyLines: true,
});
/**
 * @@@
 *
 * @public exported from `@promptbook/core`
 */
let DEFAULT_IS_VERBOSE = false;
/**
 * @@@
 *
 * Note: This is experimental feature
 *
 * @public exported from `@promptbook/core`
 */
function SET_IS_VERBOSE(isVerbose) {
    DEFAULT_IS_VERBOSE = isVerbose;
}
/**
 * @@@
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_IS_AUTO_INSTALLED = false;
/**
 * Function name for generated function via `ptbk make` to get the pipeline collection
 *
 * @public exported from `@promptbook/core`
 */
const DEFAULT_GET_PIPELINE_COLLECTION_FUNCTION_NAME = `getPipelineCollection`;
/**
 * @@@
 *
 * @private within the repository
 */
const IS_PIPELINE_LOGIC_VALIDATED = just(
/**/
// Note: In normal situations, we check the pipeline logic:
true);
/**
 * Note: [💞] Ignore a discrepancy between file name and entity name
 * TODO: [🧠][🧜‍♂️] Maybe join remoteServerUrl and path into single value
 */

/**
 * Make error report URL for the given error
 *
 * @private private within the repository
 */
function getErrorReportUrl(error) {
    const report = {
        title: `🐜 Error report from ${NAME}`,
        body: spaceTrim((block) => `


            \`${error.name || 'Error'}\` has occurred in the [${NAME}], please look into it @${ADMIN_GITHUB_NAME}.

            \`\`\`
            ${block(error.message || '(no error message)')}
            \`\`\`


            ## More info:

            - **Promptbook engine version:** ${PROMPTBOOK_ENGINE_VERSION}
            - **Book language version:** ${BOOK_LANGUAGE_VERSION}
            - **Time:** ${new Date().toISOString()}

            <details>
            <summary>Stack trace:</summary>

            ## Stack trace:

            \`\`\`stacktrace
            ${block(error.stack || '(empty)')}
            \`\`\`
            </details>

        `),
    };
    const reportUrl = new URL(`https://github.com/webgptorg/promptbook/issues/new`);
    reportUrl.searchParams.set('labels', 'bug');
    reportUrl.searchParams.set('assignees', ADMIN_GITHUB_NAME);
    reportUrl.searchParams.set('title', report.title);
    reportUrl.searchParams.set('body', report.body);
    return reportUrl;
}

/**
 * This error type indicates that the error should not happen and its last check before crashing with some other error
 *
 * @public exported from `@promptbook/core`
 */
class UnexpectedError extends Error {
    constructor(message) {
        super(spaceTrim$1((block) => `
                    ${block(message)}

                    Note: This error should not happen.
                    It's probbably a bug in the pipeline collection

                    Please report issue:
                    ${block(getErrorReportUrl(new Error(message)).href)}

                    Or contact us on ${ADMIN_EMAIL}

                `));
        this.name = 'UnexpectedError';
        Object.setPrototypeOf(this, UnexpectedError.prototype);
    }
}

/**
 * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
 *
 * @public exported from `@promptbook/core`
 */
class WrappedError extends Error {
    constructor(whatWasThrown) {
        const tag = `[🤮]`;
        console.error(tag, whatWasThrown);
        super(spaceTrim$1(`
                Non-Error object was thrown

                Note: Look for ${tag} in the console for more details
                Please report issue on ${ADMIN_EMAIL}
            `));
        this.name = 'WrappedError';
        Object.setPrototypeOf(this, WrappedError.prototype);
    }
}

/**
 * Helper used in catch blocks to assert that the error is an instance of `Error`
 *
 * @param whatWasThrown Any object that was thrown
 * @returns Nothing if the error is an instance of `Error`
 * @throws `WrappedError` or `UnexpectedError` if the error is not standard
 *
 * @private within the repository
 */
function assertsError(whatWasThrown) {
    // Case 1: Handle error which was rethrown as `WrappedError`
    if (whatWasThrown instanceof WrappedError) {
        const wrappedError = whatWasThrown;
        throw wrappedError;
    }
    // Case 2: Handle unexpected errors
    if (whatWasThrown instanceof UnexpectedError) {
        const unexpectedError = whatWasThrown;
        throw unexpectedError;
    }
    // Case 3: Handle standard errors - keep them up to consumer
    if (whatWasThrown instanceof Error) {
        return;
    }
    // Case 4: Handle non-standard errors - wrap them into `WrappedError` and throw
    throw new WrappedError(whatWasThrown);
}

/**
 * Function isValidJsonString will tell you if the string is valid JSON or not
 *
 * @public exported from `@promptbook/utils`
 */
function isValidJsonString(value /* <- [👨‍⚖️] */) {
    try {
        JSON.parse(value);
        return true;
    }
    catch (error) {
        assertsError(error);
        if (error.message.includes('Unexpected token')) {
            return false;
        }
        return false;
    }
}

/**
 * Function `validatePipelineString` will validate the if the string is a valid pipeline string
 * It does not check if the string is fully logically correct, but if it is a string that can be a pipeline string or the string looks completely different.
 *
 * @param {string} pipelineString the candidate for a pipeline string
 * @returns {PipelineString} the same string as input, but validated as valid
 * @throws {ParseError} if the string is not a valid pipeline string
 * @public exported from `@promptbook/core`
 */
function validatePipelineString(pipelineString) {
    if (isValidJsonString(pipelineString)) {
        throw new ParseError('Expected a book, but got a JSON string');
    }
    else if (isValidUrl(pipelineString)) {
        throw new ParseError(`Expected a book, but got just the URL "${pipelineString}"`);
    }
    else if (isValidFilePath(pipelineString)) {
        throw new ParseError(`Expected a book, but got just the file path "${pipelineString}"`);
    }
    else if (isValidEmail(pipelineString)) {
        throw new ParseError(`Expected a book, but got just the email "${pipelineString}"`);
    }
    // <- TODO: Implement the validation + add tests when the pipeline logic considered as invalid
    return pipelineString;
}
/**
 * TODO: [🧠][🈴] Where is the best location for this file
 */

/**
 * Prettify the html code
 *
 * @param content raw html code
 * @returns formatted html code
 * @private withing the package because of HUGE size of prettier dependency
 */
function prettifyMarkdown(content) {
    try {
        return format(content, {
            parser: 'markdown',
            plugins: [parserHtml],
            // TODO: DRY - make some import or auto-copy of .prettierrc
            endOfLine: 'lf',
            tabWidth: 4,
            singleQuote: true,
            trailingComma: 'all',
            arrowParens: 'always',
            printWidth: 120,
            htmlWhitespaceSensitivity: 'ignore',
            jsxBracketSameLine: false,
            bracketSpacing: true,
        });
    }
    catch (error) {
        // TODO: [🟥] Detect browser / node and make it colorfull
        console.error('There was an error with prettifying the markdown, using the original as the fallback', {
            error,
            html: content,
        });
        return content;
    }
}

/**
 * Makes first letter of a string uppercase
 *
 * @public exported from `@promptbook/utils`
 */
function capitalize(word) {
    return word.substring(0, 1).toUpperCase() + word.substring(1);
}

/**
 * Converts promptbook in JSON format to string format
 *
 * @deprecated TODO: [🥍][🧠] Backup original files in `PipelineJson` same as in Promptbook.studio
 * @param pipelineJson Promptbook in JSON format (.bookc)
 * @returns Promptbook in string format (.book.md)
 * @public exported from `@promptbook/core`
 */
function pipelineJsonToString(pipelineJson) {
    const { title, pipelineUrl, bookVersion, description, parameters, tasks } = pipelineJson;
    let pipelineString = `# ${title}`;
    if (description) {
        pipelineString += '\n\n';
        pipelineString += description;
    }
    const commands = [];
    if (pipelineUrl) {
        commands.push(`PIPELINE URL ${pipelineUrl}`);
    }
    if (bookVersion !== `undefined`) {
        commands.push(`BOOK VERSION ${bookVersion}`);
    }
    // TODO: [main] !!5 This increases size of the bundle and is probbably not necessary
    pipelineString = prettifyMarkdown(pipelineString);
    for (const parameter of parameters.filter(({ isInput }) => isInput)) {
        commands.push(`INPUT PARAMETER ${taskParameterJsonToString(parameter)}`);
    }
    for (const parameter of parameters.filter(({ isOutput }) => isOutput)) {
        commands.push(`OUTPUT PARAMETER ${taskParameterJsonToString(parameter)}`);
    }
    pipelineString += '\n\n';
    pipelineString += commands.map((command) => `- ${command}`).join('\n');
    for (const task of tasks) {
        const { 
        /* Note: Not using:> name, */
        title, description, 
        /* Note: dependentParameterNames, */
        jokerParameterNames: jokers, taskType, content, postprocessingFunctionNames: postprocessing, expectations, format, resultingParameterName, } = task;
        pipelineString += '\n\n';
        pipelineString += `## ${title}`;
        if (description) {
            pipelineString += '\n\n';
            pipelineString += description;
        }
        const commands = [];
        let contentLanguage = 'text';
        if (taskType === 'PROMPT_TASK') {
            const { modelRequirements } = task;
            const { modelName, modelVariant } = modelRequirements || {};
            // Note: Do nothing, it is default
            // commands.push(`PROMPT`);
            if (modelVariant) {
                commands.push(`MODEL VARIANT ${capitalize(modelVariant)}`);
            }
            if (modelName) {
                commands.push(`MODEL NAME \`${modelName}\``);
            }
        }
        else if (taskType === 'SIMPLE_TASK') {
            commands.push(`SIMPLE TEMPLATE`);
            // Note: Nothing special here
        }
        else if (taskType === 'SCRIPT_TASK') {
            commands.push(`SCRIPT`);
            if (task.contentLanguage) {
                contentLanguage = task.contentLanguage;
            }
            else {
                contentLanguage = '';
            }
        }
        else if (taskType === 'DIALOG_TASK') {
            commands.push(`DIALOG`);
            // Note: Nothing special here
        } // <- }else if([🅱]
        if (jokers) {
            for (const joker of jokers) {
                commands.push(`JOKER {${joker}}`);
            }
        } /* not else */
        if (postprocessing) {
            for (const postprocessingFunctionName of postprocessing) {
                commands.push(`POSTPROCESSING \`${postprocessingFunctionName}\``);
            }
        } /* not else */
        if (expectations) {
            for (const [unit, { min, max }] of Object.entries(expectations)) {
                if (min === max) {
                    commands.push(`EXPECT EXACTLY ${min} ${capitalize(unit + (min > 1 ? 's' : ''))}`);
                }
                else {
                    if (min !== undefined) {
                        commands.push(`EXPECT MIN ${min} ${capitalize(unit + (min > 1 ? 's' : ''))}`);
                    } /* not else */
                    if (max !== undefined) {
                        commands.push(`EXPECT MAX ${max} ${capitalize(unit + (max > 1 ? 's' : ''))}`);
                    }
                }
            }
        } /* not else */
        if (format) {
            if (format === 'JSON') {
                // TODO: @deprecated remove
                commands.push(`FORMAT JSON`);
            }
        } /* not else */
        pipelineString += '\n\n';
        pipelineString += commands.map((command) => `- ${command}`).join('\n');
        pipelineString += '\n\n';
        pipelineString += '```' + contentLanguage;
        pipelineString += '\n';
        pipelineString += spaceTrim(content);
        //                   <- TODO: [main] !!3 Escape
        //                   <- TODO: [🧠] Some clear strategy how to spaceTrim the blocks
        pipelineString += '\n';
        pipelineString += '```';
        pipelineString += '\n\n';
        pipelineString += `\`-> {${resultingParameterName}}\``; // <- TODO: [main] !!3 If the parameter here has description, add it and use taskParameterJsonToString
    }
    return validatePipelineString(pipelineString);
}
/**
 * @private internal utility of `pipelineJsonToString`
 */
function taskParameterJsonToString(taskParameterJson) {
    const { name, description } = taskParameterJson;
    let parameterString = `{${name}}`;
    if (description) {
        parameterString = `${parameterString} ${description}`;
    }
    return parameterString;
}
/**
 * TODO: [🛋] Implement new features and commands into `pipelineJsonToString` + `taskParameterJsonToString` , use `stringifyCommand`
 * TODO: [🧠] Is there a way to auto-detect missing features in pipelineJsonToString
 * TODO: [🏛] Maybe make some markdown builder
 * TODO: [🏛] Escape all
 * TODO: [🧠] Should be in generated .book.md file GENERATOR_WARNING
 */

/**
 * Orders JSON object by keys
 *
 * @returns The same type of object as the input re-ordered
 * @public exported from `@promptbook/utils`
 */
function orderJson(options) {
    const { value, order } = options;
    const orderedValue = {
        ...(order === undefined ? {} : Object.fromEntries(order.map((key) => [key, undefined]))),
        ...value,
    };
    return orderedValue;
}

/**
 * Freezes the given object and all its nested objects recursively
 *
 * Note: `$` is used to indicate that this function is not a pure function - it mutates given object
 * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
 *
 * @returns The same object as the input, but deeply frozen
 * @public exported from `@promptbook/utils`
 */
function $deepFreeze(objectValue) {
    if (Array.isArray(objectValue)) {
        return Object.freeze(objectValue.map((item) => $deepFreeze(item)));
    }
    const propertyNames = Object.getOwnPropertyNames(objectValue);
    for (const propertyName of propertyNames) {
        const value = objectValue[propertyName];
        if (value && typeof value === 'object') {
            $deepFreeze(value);
        }
    }
    Object.freeze(objectValue);
    return objectValue;
}
/**
 * TODO: [🧠] Is there a way how to meaningfully test this utility
 */

/**
 * Checks if the value is [🚉] serializable as JSON
 * If not, throws an UnexpectedError with a rich error message and tracking
 *
 * - Almost all primitives are serializable BUT:
 * - `undefined` is not serializable
 * - `NaN` is not serializable
 * - Objects and arrays are serializable if all their properties are serializable
 * - Functions are not serializable
 * - Circular references are not serializable
 * - `Date` objects are not serializable
 * - `Map` and `Set` objects are not serializable
 * - `RegExp` objects are not serializable
 * - `Error` objects are not serializable
 * - `Symbol` objects are not serializable
 * - And much more...
 *
 * @throws UnexpectedError if the value is not serializable as JSON
 * @public exported from `@promptbook/utils`
 */
function checkSerializableAsJson(options) {
    const { value, name, message } = options;
    if (value === undefined) {
        throw new UnexpectedError(`${name} is undefined`);
    }
    else if (value === null) {
        return;
    }
    else if (typeof value === 'boolean') {
        return;
    }
    else if (typeof value === 'number' && !isNaN(value)) {
        return;
    }
    else if (typeof value === 'string') {
        return;
    }
    else if (typeof value === 'symbol') {
        throw new UnexpectedError(`${name} is symbol`);
    }
    else if (typeof value === 'function') {
        throw new UnexpectedError(`${name} is function`);
    }
    else if (typeof value === 'object' && Array.isArray(value)) {
        for (let i = 0; i < value.length; i++) {
            checkSerializableAsJson({ name: `${name}[${i}]`, value: value[i], message });
        }
    }
    else if (typeof value === 'object') {
        if (value instanceof Date) {
            throw new UnexpectedError(spaceTrim((block) => `
                        \`${name}\` is Date

                        Use \`string_date_iso8601\` instead

                        Additional message for \`${name}\`:
                        ${block(message || '(nothing)')}
                    `));
        }
        else if (value instanceof Map) {
            throw new UnexpectedError(`${name} is Map`);
        }
        else if (value instanceof Set) {
            throw new UnexpectedError(`${name} is Set`);
        }
        else if (value instanceof RegExp) {
            throw new UnexpectedError(`${name} is RegExp`);
        }
        else if (value instanceof Error) {
            throw new UnexpectedError(spaceTrim((block) => `
                        \`${name}\` is unserialized Error

                        Use function \`serializeError\`

                        Additional message for \`${name}\`:
                        ${block(message || '(nothing)')}

                    `));
        }
        else {
            for (const [subName, subValue] of Object.entries(value)) {
                if (subValue === undefined) {
                    // Note: undefined in object is serializable - it is just omited
                    continue;
                }
                checkSerializableAsJson({ name: `${name}.${subName}`, value: subValue, message });
            }
            try {
                JSON.stringify(value); // <- TODO: [0]
            }
            catch (error) {
                assertsError(error);
                throw new UnexpectedError(spaceTrim((block) => `
                            \`${name}\` is not serializable

                            ${block(error.stack || error.message)}

                            Additional message for \`${name}\`:
                            ${block(message || '(nothing)')}
                        `));
            }
            /*
            TODO: [0] Is there some more elegant way to check circular references?
            const seen = new Set();
            const stack = [{ value }];
            while (stack.length > 0) {
                const { value } = stack.pop()!;
                if (typeof value === 'object' && value !== null) {
                    if (seen.has(value)) {
                        throw new UnexpectedError(`${name} has circular reference`);
                    }
                    seen.add(value);
                    if (Array.isArray(value)) {
                        stack.push(...value.map((value) => ({ value })));
                    } else {
                        stack.push(...Object.values(value).map((value) => ({ value })));
                    }
                }
            }
            */
            return;
        }
    }
    else {
        throw new UnexpectedError(spaceTrim((block) => `
                    \`${name}\` is unknown type

                    Additional message for \`${name}\`:
                    ${block(message || '(nothing)')}
                `));
    }
}
/**
 * TODO: Can be return type more type-safe? like `asserts options.value is JsonValue`
 * TODO: [🧠][main] !!3 In-memory cache of same values to prevent multiple checks
 * Note: [🐠] This is how `checkSerializableAsJson` + `isSerializableAsJson` together can just retun true/false or rich error message
 */

/**
 * @@@
 *
 * @public exported from `@promptbook/utils`
 */
function deepClone(objectValue) {
    return JSON.parse(JSON.stringify(objectValue));
    /*
    TODO: [🧠] Is there a better implementation?
    > const propertyNames = Object.getOwnPropertyNames(objectValue);
    > for (const propertyName of propertyNames) {
    >     const value = (objectValue as really_any)[propertyName];
    >     if (value && typeof value === 'object') {
    >         deepClone(value);
    >     }
    > }
    > return Object.assign({}, objectValue);
    */
}
/**
 * TODO: [🧠] Is there a way how to meaningfully test this utility
 */

/**
 * Utility to export a JSON object from a function
 *
 * 1) Checks if the value is serializable as JSON
 * 2) Makes a deep clone of the object
 * 2) Orders the object properties
 * 2) Deeply freezes the cloned object
 *
 * Note: This function does not mutates the given object
 *
 * @returns The same type of object as the input but read-only and re-ordered
 * @public exported from `@promptbook/utils`
 */
function exportJson(options) {
    const { name, value, order, message } = options;
    checkSerializableAsJson({ name, value, message });
    const orderedValue = 
    // TODO: Fix error "Type instantiation is excessively deep and possibly infinite."
    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
    // @ts-ignore
    order === undefined
        ? deepClone(value)
        : orderJson({
            value: value,
            // <- Note: checkSerializableAsJson asserts that the value is serializable as JSON
            order: order,
        });
    $deepFreeze(orderedValue);
    return orderedValue;
}
/**
 * TODO: [🧠] Is there a way how to meaningfully test this utility
 */

/**
 * Order of keys in the pipeline JSON
 *
 * @public exported from `@promptbook/core`
 */
const ORDER_OF_PIPELINE_JSON = [
    // Note: [🍙] In this order will be pipeline serialized
    'title',
    'pipelineUrl',
    'bookVersion',
    'description',
    'formfactorName',
    'parameters',
    'tasks',
    'personas',
    'preparations',
    'knowledgeSources',
    'knowledgePieces',
    'sources', // <- TODO: [🧠] Where should the `sources` be
];
/**
 * Nonce which is used for replacing things in strings
 *
 * @private within the repository
 */
const REPLACING_NONCE = 'ptbkauk42kV2dzao34faw7FudQUHYPtW';
/**
 * @@@
 *
 * @private within the repository
 */
const RESERVED_PARAMETER_MISSING_VALUE = 'MISSING-' + REPLACING_NONCE;
/**
 * @@@
 *
 * @private within the repository
 */
const RESERVED_PARAMETER_RESTRICTED = 'RESTRICTED-' + REPLACING_NONCE;
/**
 * The names of the parameters that are reserved for special purposes
 *
 * @public exported from `@promptbook/core`
 */
const RESERVED_PARAMETER_NAMES = exportJson({
    name: 'RESERVED_PARAMETER_NAMES',
    message: `The names of the parameters that are reserved for special purposes`,
    value: [
        'content',
        'context',
        'knowledge',
        'examples',
        'modelName',
        'currentDate',
        // <- TODO: list here all command names
        // <- TODO: Add more like 'date', 'modelName',...
        // <- TODO: Add [emoji] + instructions ACRY when adding new reserved parameter
    ],
});
/**
 * Note: [💞] Ignore a discrepancy between file name and entity name
 */

/**
 * This error indicates that the promptbook object has valid syntax (=can be parsed) but contains logical errors (like circular dependencies)
 *
 * @public exported from `@promptbook/core`
 */
class PipelineLogicError extends Error {
    constructor(message) {
        super(message);
        this.name = 'PipelineLogicError';
        Object.setPrototypeOf(this, PipelineLogicError.prototype);
    }
}

/**
 * Tests if given string is valid semantic version
 *
 * Note: There are two simmilar functions:
 * - `isValidSemanticVersion` which tests any semantic version
 * - `isValidPromptbookVersion` *(this one)* which tests just Promptbook versions
 *
 * @public exported from `@promptbook/utils`
 */
function isValidSemanticVersion(version) {
    if (typeof version !== 'string') {
        return false;
    }
    if (version.startsWith('0.0.0')) {
        return false;
    }
    return /^\d+\.\d+\.\d+(-\d+)?$/i.test(version);
}

/**
 * Tests if given string is valid promptbook version
 * It looks into list of known promptbook versions.
 *
 * @see https://www.npmjs.com/package/promptbook?activeTab=versions
 * Note: When you are using for example promptbook 2.0.0 and there already is promptbook 3.0.0 it don`t know about it.
 * Note: There are two simmilar functions:
 * - `isValidSemanticVersion` which tests any semantic version
 * - `isValidPromptbookVersion` *(this one)* which tests just Promptbook versions
 *
 * @public exported from `@promptbook/utils`
 */
function isValidPromptbookVersion(version) {
    if (!isValidSemanticVersion(version)) {
        return false;
    }
    if ( /* version === '1.0.0' || */version === '2.0.0' || version === '3.0.0') {
        return false;
    }
    // <- TODO: [main] !!3 Check isValidPromptbookVersion against PROMPTBOOK_ENGINE_VERSIONS
    return true;
}

/**
 * Tests if given string is valid pipeline URL URL.
 *
 * Note: There are two simmilar functions:
 * - `isValidUrl` which tests any URL
 * - `isValidPipelineUrl` *(this one)* which tests just pipeline URL
 *
 * @public exported from `@promptbook/utils`
 */
function isValidPipelineUrl(url) {
    if (!isValidUrl(url)) {
        return false;
    }
    if (!url.startsWith('https://') && !url.startsWith('http://') /* <- Note: [👣] */) {
        return false;
    }
    if (url.includes('#')) {
        // TODO: [🐠]
        return false;
    }
    /*
    Note: [👣][🧠] Is it secure to allow pipeline URLs on private and unsecured networks?
    if (isUrlOnPrivateNetwork(url)) {
        return false;
    }
    */
    return true;
}
/**
 * TODO: [🐠] Maybe more info why the URL is invalid
 */

/**
 * Validates PipelineJson if it is logically valid
 *
 * It checks:
 * -   if it has correct parameters dependency
 *
 * It does NOT check:
 * -   if it is valid json
 * -   if it is meaningful
 *
 * @param pipeline valid or invalid PipelineJson
 * @returns the same pipeline if it is logically valid
 * @throws {PipelineLogicError} on logical error in the pipeline
 * @public exported from `@promptbook/core`
 */
function validatePipeline(pipeline) {
    if (IS_PIPELINE_LOGIC_VALIDATED) {
        validatePipeline_InnerFunction(pipeline);
    }
    else {
        try {
            validatePipeline_InnerFunction(pipeline);
        }
        catch (error) {
            if (!(error instanceof PipelineLogicError)) {
                throw error;
            }
            console.error(spaceTrim$1((block) => `
                        Pipeline is not valid but logic errors are temporarily disabled via \`IS_PIPELINE_LOGIC_VALIDATED\`

                        ${block(error.message)}
                    `));
        }
    }
    return pipeline;
}
/**
 * @private internal function for `validatePipeline`
 */
function validatePipeline_InnerFunction(pipeline) {
    // TODO: [🧠] Maybe test if promptbook is a promise and make specific error case for that
    const pipelineIdentification = (() => {
        // Note: This is a 😐 implementation of [🚞]
        const _ = [];
        if (pipeline.sourceFile !== undefined) {
            _.push(`File: ${pipeline.sourceFile}`);
        }
        if (pipeline.pipelineUrl !== undefined) {
            _.push(`Url: ${pipeline.pipelineUrl}`);
        }
        return _.join('\n');
    })();
    if (pipeline.pipelineUrl !== undefined && !isValidPipelineUrl(pipeline.pipelineUrl)) {
        // <- Note: [🚲]
        throw new PipelineLogicError(spaceTrim$1((block) => `
                    Invalid promptbook URL "${pipeline.pipelineUrl}"

                    ${block(pipelineIdentification)}
                `));
    }
    if (pipeline.bookVersion !== undefined && !isValidPromptbookVersion(pipeline.bookVersion)) {
        // <- Note: [🚲]
        throw new PipelineLogicError(spaceTrim$1((block) => `
                    Invalid Promptbook Version "${pipeline.bookVersion}"

                    ${block(pipelineIdentification)}
                `));
    }
    // TODO: [🧠] Maybe do here some propper JSON-schema / ZOD checking
    if (!Array.isArray(pipeline.parameters)) {
        // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
        throw new ParseError(spaceTrim$1((block) => `
                    Pipeline is valid JSON but with wrong structure

                    \`PipelineJson.parameters\` expected to be an array, but got ${typeof pipeline.parameters}

                    ${block(pipelineIdentification)}
                `));
    }
    // TODO: [🧠] Maybe do here some propper JSON-schema / ZOD checking
    if (!Array.isArray(pipeline.tasks)) {
        // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
        throw new ParseError(spaceTrim$1((block) => `
                    Pipeline is valid JSON but with wrong structure

                    \`PipelineJson.tasks\` expected to be an array, but got ${typeof pipeline.tasks}

                    ${block(pipelineIdentification)}
                `));
    }
    /*
    TODO: [🧠][🅾] Should be empty pipeline valid or not
    // Note: Check that pipeline has some tasks
    if (pipeline.tasks.length === 0) {
        throw new PipelineLogicError(
            spaceTrim(
                (block) => `
                  Pipeline must have at least one task

                  ${block(pipelineIdentification)}
              `,
            ),
        );
    }
    */
    // Note: Check each parameter individually
    for (const parameter of pipeline.parameters) {
        if (parameter.isInput && parameter.isOutput) {
            throw new PipelineLogicError(spaceTrim$1((block) => `

                        Parameter \`{${parameter.name}}\` can not be both input and output

                        ${block(pipelineIdentification)}
                    `));
        }
        // Note: Testing that parameter is either intermediate or output BUT not created and unused
        if (!parameter.isInput &&
            !parameter.isOutput &&
            !pipeline.tasks.some((task) => task.dependentParameterNames.includes(parameter.name))) {
            throw new PipelineLogicError(spaceTrim$1((block) => `
                        Parameter \`{${parameter.name}}\` is created but not used

                        You can declare {${parameter.name}} as output parameter by adding in the header:
                        - OUTPUT PARAMETER \`{${parameter.name}}\` ${parameter.description || ''}

                        ${block(pipelineIdentification)}

                    `));
        }
        // Note: Testing that parameter is either input or result of some task
        if (!parameter.isInput && !pipeline.tasks.some((task) => task.resultingParameterName === parameter.name)) {
            throw new PipelineLogicError(spaceTrim$1((block) => `
                        Parameter \`{${parameter.name}}\` is declared but not defined

                        You can do one of these:
                        1) Remove declaration of \`{${parameter.name}}\`
                        2) Add task that results in \`-> {${parameter.name}}\`

                        ${block(pipelineIdentification)}
                    `));
        }
    }
    // Note: All input parameters are defined - so that they can be used as result of some task
    const definedParameters = new Set(pipeline.parameters.filter(({ isInput }) => isInput).map(({ name }) => name));
    // Note: Checking each task individually
    for (const task of pipeline.tasks) {
        if (definedParameters.has(task.resultingParameterName)) {
            throw new PipelineLogicError(spaceTrim$1((block) => `
                        Parameter \`{${task.resultingParameterName}}\` is defined multiple times

                        ${block(pipelineIdentification)}
                    `));
        }
        if (RESERVED_PARAMETER_NAMES.includes(task.resultingParameterName)) {
            throw new PipelineLogicError(spaceTrim$1((block) => `
                        Parameter name {${task.resultingParameterName}} is reserved, please use different name

                        ${block(pipelineIdentification)}
                    `));
        }
        definedParameters.add(task.resultingParameterName);
        if (task.jokerParameterNames && task.jokerParameterNames.length > 0) {
            if (!task.format &&
                !task.expectations /* <- TODO: Require at least 1 -> min <- expectation to use jokers */) {
                throw new PipelineLogicError(spaceTrim$1((block) => `
                            Joker parameters are used for {${task.resultingParameterName}} but no expectations are defined

                            ${block(pipelineIdentification)}
                        `));
            }
            for (const joker of task.jokerParameterNames) {
                if (!task.dependentParameterNames.includes(joker)) {
                    throw new PipelineLogicError(spaceTrim$1((block) => `
                                Parameter \`{${joker}}\` is used for {${task.resultingParameterName}} as joker but not in \`dependentParameterNames\`

                                ${block(pipelineIdentification)}
                            `));
                }
            }
        }
        if (task.expectations) {
            for (const [unit, { min, max }] of Object.entries(task.expectations)) {
                if (min !== undefined && max !== undefined && min > max) {
                    throw new PipelineLogicError(spaceTrim$1((block) => `
                                Min expectation (=${min}) of ${unit} is higher than max expectation (=${max})

                                ${block(pipelineIdentification)}
                            `));
                }
                if (min !== undefined && min < 0) {
                    throw new PipelineLogicError(spaceTrim$1((block) => `
                                Min expectation of ${unit} must be zero or positive

                                ${block(pipelineIdentification)}
                            `));
                }
                if (max !== undefined && max <= 0) {
                    throw new PipelineLogicError(spaceTrim$1((block) => `
                                Max expectation of ${unit} must be positive

                                ${block(pipelineIdentification)}
                            `));
                }
            }
        }
    }
    // Note: Detect circular dependencies
    let resovedParameters = pipeline.parameters
        .filter(({ isInput }) => isInput)
        .map(({ name }) => name);
    // Note: All reserved parameters are resolved
    for (const reservedParameterName of RESERVED_PARAMETER_NAMES) {
        resovedParameters = [...resovedParameters, reservedParameterName];
    }
    let unresovedTasks = [...pipeline.tasks];
    let loopLimit = LOOP_LIMIT;
    while (unresovedTasks.length > 0) {
        if (loopLimit-- < 0) {
            // Note: Really UnexpectedError not LimitReachedError - this should not happen and be caught below
            throw new UnexpectedError(spaceTrim$1((block) => `
                        Loop limit reached during detection of circular dependencies in \`validatePipeline\`

                        ${block(pipelineIdentification)}
                    `));
        }
        const currentlyResovedTasks = unresovedTasks.filter((task) => task.dependentParameterNames.every((name) => resovedParameters.includes(name)));
        if (currentlyResovedTasks.length === 0) {
            throw new PipelineLogicError(
            // TODO: [🐎] DRY
            spaceTrim$1((block) => `

                        Can not resolve some parameters:
                        Either you are using a parameter that is not defined, or there are some circular dependencies.

                        ${block(pipelineIdentification)}

                        **Can not resolve:**
                        ${block(unresovedTasks
                .map(({ resultingParameterName, dependentParameterNames }) => `- Parameter \`{${resultingParameterName}}\` which depends on ${dependentParameterNames
                .map((dependentParameterName) => `\`{${dependentParameterName}}\``)
                .join(' and ')}`)
                .join('\n'))}

                        **Resolved:**
                        ${block(resovedParameters
                .filter((name) => !RESERVED_PARAMETER_NAMES.includes(name))
                .map((name) => `- Parameter \`{${name}}\``)
                .join('\n'))}


                        **Reserved (which are available):**
                        ${block(resovedParameters
                .filter((name) => RESERVED_PARAMETER_NAMES.includes(name))
                .map((name) => `- Parameter \`{${name}}\``)
                .join('\n'))}


                    `));
        }
        resovedParameters = [
            ...resovedParameters,
            ...currentlyResovedTasks.map(({ resultingParameterName }) => resultingParameterName),
        ];
        unresovedTasks = unresovedTasks.filter((task) => !currentlyResovedTasks.includes(task));
    }
    // Note: Check that formfactor is corresponding to the pipeline interface
    // TODO: !!6 Implement this
    // pipeline.formfactorName
}
/**
 * TODO: [🧞‍♀️] Do not allow joker + foreach
 * TODO: [🧠] Work with promptbookVersion
 * TODO: Use here some json-schema, Zod or something similar and change it to:
 *     > /**
 *     >  * Validates PipelineJson if it is logically valid.
 *     >  *
 *     >  * It checks:
 *     >  * -   it has a valid structure
 *     >  * -   ...
 *     >  ex port function validatePipeline(promptbook: really_unknown): asserts promptbook is PipelineJson {
 */
/**
 * TODO: [🧳][main] !!4 Validate that all examples match expectations
 * TODO: [🧳][🐝][main] !!4 Validate that knowledge is valid (non-void)
 * TODO: [🧳][main] !!4 Validate that persona can be used only with CHAT variant
 * TODO: [🧳][main] !!4 Validate that parameter with reserved name not used RESERVED_PARAMETER_NAMES
 * TODO: [🧳][main] !!4 Validate that reserved parameter is not used as joker
 * TODO: [🧠] Validation not only logic itself but imports around - files and websites and rerefenced pipelines exists
 * TODO: [🛠] Actions, instruments (and maybe knowledge) => Functions and tools
 */

/**
 * This error