@promptbook/remote-client 0.112.0-39 → 0.112.0-41

package/umd/index.umd.js

@@ -22,7 +22,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-39';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-41';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -6199,6 +6199,42 @@
     }
     // TODO: [🔣] If script require contentLanguage
 
+    /**
+     * Normalizes inline parameter mentions wrapped in code spans before markdown flattening.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    const INLINE_CODE_PARAMETER_REGEXP = /`\{(?<parameterName>[a-z0-9_]+)\}`/gi;
+    /**
+     * Normalizes inline return statements wrapped in code spans before markdown flattening.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    const INLINE_CODE_RETURN_PARAMETER_REGEXP = /`->\s+\{(?<parameterName>[a-z0-9_]+)\}`/gi;
+    /**
+     * Matches the trailing return statement of a task section.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    const RESULTING_PARAMETER_LINE_REGEXP = /^->\s*\{(?<resultingParamName>[a-z0-9_]+)\}/im;
+    /**
+     * Removes fenced code blocks when deriving human-readable section descriptions.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    const DESCRIPTION_CODE_BLOCK_REGEXP = /^```.*^```/gms;
+    /**
+     * Removes blockquote lines when deriving human-readable section descriptions.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    const DESCRIPTION_BLOCKQUOTE_REGEXP = /^>.*$/gm;
+    /**
+     * Removes list items and return statements when deriving human-readable section descriptions.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    const DESCRIPTION_LIST_ITEM_REGEXP = /^(?:(?:-)|(?:\d\))|(?:`?->))\s+.*$/gm;
     /**
      * Compile pipeline from string (markdown) format to JSON format synchronously
      *
@@ -6217,7 +6253,27 @@
      * @public exported from `@promptbook/core`
      */
     function parsePipeline(pipelineString) {
-        const $pipelineJson = {
+        const $pipelineJson = createInitialPipelineJson(pipelineString);
+        const preparedPipelineString = preparePipelineString(pipelineString, $pipelineJson);
+        const { pipelineHead, pipelineSections } = parsePreparedPipelineSections(preparedPipelineString, $pipelineJson);
+        const getUniqueSectionName = createUniqueSectionNameResolver(pipelineSections);
+        applyPipelineHead(pipelineHead, $pipelineJson);
+        for (const pipelineSection of pipelineSections) {
+            processPipelineSection(pipelineSection, $pipelineJson, getUniqueSectionName);
+        }
+        applyImplicitParameterDirections($pipelineJson);
+        removeUndefinedValuesFromPipeline($pipelineJson);
+        applySyncHighLevelAbstractions($pipelineJson);
+        ensurePipelineFormfactor($pipelineJson);
+        return exportParsedPipelineJson($pipelineJson);
+    }
+    /**
+     * Creates the mutable pipeline JSON structure used throughout parsing.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function createInitialPipelineJson(pipelineString) {
+        return {
             title: DEFAULT_BOOK_TITLE,
             parameters: [],
             tasks: [],
@@ -6234,56 +6290,90 @@
                 },
             ],
         };
-        function getPipelineIdentification() {
-            // Note: This is a 😐 implementation of [🚞]
-            const _ = [];
-            if ($pipelineJson.sourceFile !== undefined) {
-                _.push(`File: ${$pipelineJson.sourceFile}`);
-            }
-            if ($pipelineJson.pipelineUrl !== undefined) {
-                _.push(`Url: ${$pipelineJson.pipelineUrl}`);
-            }
-            return _.join('\n');
-        }
-        // =============================================================
-        // Note: 1️⃣ Parsing of the markdown into object
-        // ==============
-        // Note: 1️⃣◽1️⃣ Remove #!shebang and comments
-        if (pipelineString.startsWith('#!')) {
-            const [shebangLine, ...restLines] = pipelineString.split(/\r?\n/);
-            if (!(shebangLine || '').includes('ptbk')) {
-                throw new ParseError(spacetrim.spaceTrim((block) => `
-                        It seems that you try to parse a book file which has non-standard shebang line for book files:
-                        Shebang line must contain 'ptbk'
-
-                        You have:
-                        ${block(shebangLine || '(empty line)')}
-
-                        It should look like this:
-                        #!/usr/bin/env ptbk
-
-                        ${block(getPipelineIdentification())}
-                    `));
-            }
-            pipelineString = validatePipelineString(restLines.join('\n'));
+    }
+    /**
+     * Builds a short file/url identification block for parse errors.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function getPipelineIdentification($pipelineJson) {
+        // Note: This is a 😐 implementation of [🚞]
+        const pipelineIdentificationParts = [];
+        if ($pipelineJson.sourceFile !== undefined) {
+            pipelineIdentificationParts.push(`File: ${$pipelineJson.sourceFile}`);
         }
+        if ($pipelineJson.pipelineUrl !== undefined) {
+            pipelineIdentificationParts.push(`Url: ${$pipelineJson.pipelineUrl}`);
+        }
+        return pipelineIdentificationParts.join('\n');
+    }
+    /**
+     * Removes shebang/comments and normalizes markdown into a parseable pipeline form.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function preparePipelineString(pipelineString, $pipelineJson) {
+        pipelineString = removePipelineShebang(pipelineString, $pipelineJson);
         pipelineString = removeMarkdownComments(pipelineString);
         pipelineString = spacetrim.spaceTrim(pipelineString);
         // <- TODO: [😧] `spaceTrim` should preserve discriminated type *(or at lease `PipelineString`)*
         pipelineString = deflatePipeline(pipelineString);
-        // ==============
-        // Note: 1️⃣◽2️⃣ Parse the markdown
-        pipelineString = flattenMarkdown(pipelineString) /* <- Note: [🥞] */;
-        pipelineString = pipelineString.replaceAll(/`\{(?<parameterName>[a-z0-9_]+)\}`/gi, '{$<parameterName>}');
-        pipelineString = pipelineString.replaceAll(/`->\s+\{(?<parameterName>[a-z0-9_]+)\}`/gi, '-> {$<parameterName>}');
+        pipelineString = flattenMarkdown(pipelineString);
+        pipelineString = pipelineString.replaceAll(INLINE_CODE_PARAMETER_REGEXP, '{$<parameterName>}');
+        pipelineString = pipelineString.replaceAll(INLINE_CODE_RETURN_PARAMETER_REGEXP, '-> {$<parameterName>}');
+        return pipelineString;
+    }
+    /**
+     * Validates and removes the optional `#!` shebang line for `.book` files.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function removePipelineShebang(pipelineString, $pipelineJson) {
+        if (!pipelineString.startsWith('#!')) {
+            return pipelineString;
+        }
+        const [shebangLine, ...restLines] = pipelineString.split(/\r?\n/);
+        const isBookShebang = (shebangLine || '').includes('ptbk');
+        if (!isBookShebang) {
+            throw new ParseError(spacetrim.spaceTrim((block) => `
+                    It seems that you try to parse a book file which has non-standard shebang line for book files:
+                    Shebang line must contain 'ptbk'
+
+                    You have:
+                    ${block(shebangLine || '(empty line)')}
+
+                    It should look like this:
+                    #!/usr/bin/env ptbk
+
+                    ${block(getPipelineIdentification($pipelineJson))}
+                `));
+        }
+        return validatePipelineString(restLines.join('\n'));
+    }
+    /**
+     * Splits the prepared markdown into the pipeline head and task sections.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function parsePreparedPipelineSections(pipelineString, $pipelineJson) {
         const [pipelineHead, ...pipelineSections] = splitMarkdownIntoSections(pipelineString).map(parseMarkdownSection); /* <- Note: [🥞] */
-        // ==============
-        // Note: 1️⃣◽4️⃣ Check markdown structure
+        assertPipelineSectionsStructure(pipelineHead, pipelineSections, $pipelineJson);
+        return {
+            pipelineHead,
+            pipelineSections,
+        };
+    }
+    /**
+     * Ensures the flattened markdown has exactly one h1 head followed by only h2 sections.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function assertPipelineSectionsStructure(pipelineHead, pipelineSections, $pipelineJson) {
         if (pipelineHead === undefined) {
             throw new UnexpectedError(spacetrim.spaceTrim((block) => `
                     Pipeline head is not defined
 
-                    ${block(getPipelineIdentification())}
+                    ${block(getPipelineIdentification($pipelineJson))}
 
                     This should never happen, because the pipeline already flattened
                 `));
@@ -6292,337 +6382,463 @@
             throw new UnexpectedError(spacetrim.spaceTrim((block) => `
                     Pipeline head is not h1
 
-                    ${block(getPipelineIdentification())}
+                    ${block(getPipelineIdentification($pipelineJson))}
 
                     This should never happen, because the pipeline already flattened
                 `));
         }
-        if (!pipelineSections.every((section) => section.level === 2)) {
+        if (!pipelineSections.every((pipelineSection) => pipelineSection.level === 2)) {
             throw new UnexpectedError(spacetrim.spaceTrim((block) => `
                     Not every pipeline section is h2
 
-                    ${block(getPipelineIdentification())}
+                    ${block(getPipelineIdentification($pipelineJson))}
 
                     This should never happen, because the pipeline already flattened
                 `));
         }
-        // =============================================================
-        ///Note: 2️⃣ Function for defining parameters
-        const defineParam = (parameterCommand) => {
-            const { parameterName, parameterDescription, isInput, isOutput } = parameterCommand;
-            if (RESERVED_PARAMETER_NAMES.includes(parameterName)) {
-                throw new ParseError(spacetrim.spaceTrim((block) => `
-                        Parameter name {${parameterName}} is reserved and cannot be used as resulting parameter name
+    }
+    /**
+     * Applies the pipeline head title, description, and head-level commands.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function applyPipelineHead(pipelineHead, $pipelineJson) {
+        $pipelineJson.title = pipelineHead.title;
+        $pipelineJson.description = extractPipelineDescription(pipelineHead.content);
+        for (const listItem of extractAllListItemsFromMarkdown(pipelineHead.content)) {
+            applyPipelineHeadCommand(listItem, $pipelineJson);
+        }
+    }
+    /**
+     * Extracts the plain-text description from a head or task section body.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function extractPipelineDescription(sectionContent) {
+        let description = sectionContent;
+        description = description.split(DESCRIPTION_CODE_BLOCK_REGEXP).join('');
+        description = description.split(DESCRIPTION_BLOCKQUOTE_REGEXP).join('');
+        description = description.split(DESCRIPTION_LIST_ITEM_REGEXP).join('');
+        description = spacetrim.spaceTrim(description);
+        if (description === '') {
+            return undefined;
+        }
+        return description;
+    }
+    /**
+     * Parses and applies one command declared in the pipeline head.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function applyPipelineHeadCommand(listItem, $pipelineJson) {
+        const command = parseCommand(listItem, 'PIPELINE_HEAD');
+        const commandParser = getParserForCommand(command);
+        if (commandParser.isUsedInPipelineHead !== true /* <- Note: [🦦][4] */) {
+            throw new ParseError(spacetrim.spaceTrim((block) => `
+                    Command \`${command.type}\` is not allowed in the head of the pipeline ONLY at the pipeline task
 
-                        ${block(getPipelineIdentification())}
-                    `) /* <- TODO: [🚞] */);
+                    ${block(getPipelineIdentification($pipelineJson))}
+                `)); // <- TODO: [🚞]
+        }
+        try {
+            commandParser.$applyToPipelineJson(command, $pipelineJson);
+            //             <- Note: [🦦] Its strange that this assertion must be here, [🦦][4] should do this assertion implicitly
+        }
+        catch (error) {
+            if (!(error instanceof ParseError)) {
+                throw error;
             }
-            const existingParameter = $pipelineJson.parameters.find((parameter) => parameter.name === parameterName);
-            if (existingParameter &&
-                existingParameter.description &&
-                existingParameter.description !== parameterDescription &&
-                parameterDescription) {
-                throw new ParseError(spacetrim.spaceTrim((block) => `
-                        Parameter \`{${parameterName}}\` is defined multiple times with different description:
+            throw new ParseError(spacetrim.spaceTrim((block) => `
+                    Command ${command.type} failed to apply to the pipeline
 
-                        ${block(getPipelineIdentification())}
+                    The error:
+                    ${block(error.message)}
 
-                        First definition:
-                        ${block(existingParameter.description || '[undefined]')}
+                    Raw command:
+                    - ${listItem}
 
-                        Second definition:
-                        ${block(parameterDescription || '[undefined]')}
-                    `));
-            }
-            if (existingParameter) {
-                if (parameterDescription) {
-                    existingParameter.description = parameterDescription;
-                }
-                existingParameter.isInput = existingParameter.isInput || isInput;
-                existingParameter.isOutput = existingParameter.isOutput || isOutput;
-            }
-            else {
-                $pipelineJson.parameters.push({
-                    name: parameterName,
-                    description: parameterDescription || undefined,
-                    isInput,
-                    isOutput,
-                });
-            }
-        };
-        // =============================================================
-        // Note: 3️⃣ Process pipeline head
-        $pipelineJson.title = pipelineHead.title;
-        // TODO: [🎾][1] DRY description
-        let description = pipelineHead.content;
-        // Note: Remove codeblocks - TODO: [🎾] Make util removeAllBlocksFromMarkdown (exported from `@promptbool/utils`)
-        description = description.split(/^```.*^```/gms).join('');
-        description = description.split(/^>.*$/gm).join('');
-        //Note: Remove lists and return statement - TODO: [🎾] Make util  (exported from `@promptbool/utils`)
-        description = description.split(/^(?:(?:-)|(?:\d\))|(?:`?->))\s+.*$/gm).join('');
-        description = spacetrim.spaceTrim(description);
-        if (description === '') {
-            description = undefined;
-        }
-        $pipelineJson.description = description;
-        const listItems = extractAllListItemsFromMarkdown(pipelineHead.content);
-        for (const listItem of listItems) {
-            // TODO: [🥥] Maybe move this logic to `$parseAndApplyPipelineHeadCommands`
-            const command = parseCommand(listItem, 'PIPELINE_HEAD');
-            const commandParser = getParserForCommand(command);
-            if (commandParser.isUsedInPipelineHead !== true /* <- Note: [🦦][4] */) {
-                throw new ParseError(spacetrim.spaceTrim((block) => `
-                        Command \`${command.type}\` is not allowed in the head of the pipeline ONLY at the pipeline task
+                    Usage of ${command.type}:
+                    ${block(commandParser.examples.map((example) => `- ${example}`).join('\n'))}
 
-                        ${block(getPipelineIdentification())}
-                    `)); // <- TODO: [🚞]
-            }
-            try {
-                commandParser.$applyToPipelineJson(command, $pipelineJson);
-                //             <- Note: [🦦] Its strange that this assertion must be here, [🦦][4] should do this assertion implicitly
-            }
-            catch (error) {
-                if (!(error instanceof ParseError)) {
-                    throw error;
-                }
-                throw new ParseError(spacetrim.spaceTrim((block) => `
-                        Command ${command.type} failed to apply to the pipeline
+                    ${block(getPipelineIdentification($pipelineJson))}
+              `)); // <- TODO: [🚞]
+        }
+        if (command.type === 'PARAMETER') {
+            defineParameter($pipelineJson, command);
+            // <- Note: [🍣]
+        }
+    }
+    /**
+     * Merges one parameter declaration into the mutable pipeline parameter list.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function defineParameter($pipelineJson, parameterCommand) {
+        const { parameterName, parameterDescription, isInput, isOutput } = parameterCommand;
+        if (RESERVED_PARAMETER_NAMES.includes(parameterName)) {
+            throw new ParseError(spacetrim.spaceTrim((block) => `
+                    Parameter name {${parameterName}} is reserved and cannot be used as resulting parameter name
 
-                        The error:
-                        ${block(error.message)}
+                    ${block(getPipelineIdentification($pipelineJson))}
+                `) /* <- TODO: [🚞] */);
+        }
+        const existingParameter = $pipelineJson.parameters.find((parameter) => parameter.name === parameterName);
+        if (existingParameter &&
+            existingParameter.description &&
+            existingParameter.description !== parameterDescription &&
+            parameterDescription) {
+            throw new ParseError(spacetrim.spaceTrim((block) => `
+                    Parameter \`{${parameterName}}\` is defined multiple times with different description:
 
-                        Raw command:
-                        - ${listItem}
+                    ${block(getPipelineIdentification($pipelineJson))}
 
-                        Usage of ${command.type}:
-                        ${block(commandParser.examples.map((example) => `- ${example}`).join('\n'))}
+                    First definition:
+                    ${block(existingParameter.description || '[undefined]')}
 
-                        ${block(getPipelineIdentification())}
-                  `)); // <- TODO: [🚞]
-            }
-            if (command.type === 'PARAMETER') {
-                defineParam(command);
-                // <- Note: [🍣]
+                    Second definition:
+                    ${block(parameterDescription || '[undefined]')}
+                `));
+        }
+        if (existingParameter) {
+            if (parameterDescription) {
+                existingParameter.description = parameterDescription;
             }
+            existingParameter.isInput = existingParameter.isInput || isInput;
+            existingParameter.isOutput = existingParameter.isOutput || isOutput;
+            return;
         }
-        // =============================================================
-        // Note: 4️⃣ Prepare unique section names with indexes when needed
+        $pipelineJson.parameters.push({
+            name: parameterName,
+            description: parameterDescription || undefined,
+            isInput,
+            isOutput,
+        });
+    }
+    /**
+     * Creates stable unique task names for duplicate section titles.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function createUniqueSectionNameResolver(pipelineSections) {
         const sectionCounts = {};
-        for (const section of pipelineSections) {
-            const name = titleToName(section.title);
-            if (sectionCounts[name] === undefined) {
-                sectionCounts[name] = { count: 0, currentIndex: 0 };
+        for (const pipelineSection of pipelineSections) {
+            const sectionName = titleToName(pipelineSection.title);
+            if (sectionCounts[sectionName] === undefined) {
+                sectionCounts[sectionName] = { count: 0, currentIndex: 0 };
             }
-            sectionCounts[name].count++;
+            sectionCounts[sectionName].count++;
         }
-        const getUniqueSectionName = (title) => {
-            const name = titleToName(title);
-            const count = sectionCounts[name];
-            if (count.count === 1) {
-                return name;
+        return (title) => {
+            const sectionName = titleToName(title);
+            const sectionCount = sectionCounts[sectionName];
+            if (sectionCount.count === 1) {
+                return sectionName;
             }
-            const nameWithSuffix = `${name}-${count.currentIndex}`;
-            count.currentIndex++;
+            const nameWithSuffix = `${sectionName}-${sectionCount.currentIndex}`;
+            sectionCount.currentIndex++;
             return nameWithSuffix;
         };
-        // =============================================================
-        // Note: 5️⃣ Process each section of the pipeline
-        for (const section of pipelineSections) {
-            // TODO: Parse section's description (the content out of the codeblock and lists)
-            const listItems = extractAllListItemsFromMarkdown(section.content);
-            const { language, content } = extractOneBlockFromMarkdown(section.content);
-            // TODO: [🎾][1] DRY description
-            let description = section.content;
-            // Note: Remove codeblocks - TODO: [🎾]
-            description = description.split(/^```.*^```/gms).join('');
-            description = description.split(/^>.*$/gm).join('');
-            //Note: Remove lists and return statement - TODO: [🎾]
-            description = description.split(/^(?:(?:-)|(?:\d\))|(?:`?->))\s+.*$/gm).join('');
-            description = spacetrim.spaceTrim(description);
-            if (description === '') {
-                description = undefined;
-            }
-            const $taskJson = {
-                isSectionTypeSet: false,
-                isTask: true,
-                taskType: undefined /* <- Note: [🍙] Putting here placeholder to keep `taskType` on top at final JSON */,
-                name: getUniqueSectionName(section.title || DEFAULT_TASK_TITLE),
-                title: section.title || DEFAULT_TASK_TITLE,
-                description,
-                content,
-                // <- TODO: [🍙] Some standard order of properties
-            };
-            const lastLine = section.content.split(/\r?\n/).pop();
-            const resultingParameterNameMatch = /^->\s*\{(?<resultingParamName>[a-z0-9_]+)\}/im.exec(lastLine);
-            if (resultingParameterNameMatch &&
-                resultingParameterNameMatch.groups !== undefined &&
-                resultingParameterNameMatch.groups.resultingParamName !== undefined) {
-                $taskJson.resultingParameterName = resultingParameterNameMatch.groups.resultingParamName;
-            }
-            // TODO: [🥥] Maybe move this logic to `$parseAndApplyPipelineTaskCommands`
-            const commands = listItems.map((listItem) => ({
-                listItem,
-                command: parseCommand(listItem, 'PIPELINE_TASK'),
-            }));
-            // Note: If block type is not set, set it to 'PROMPT_TASK'
-            if (commands.some(({ command }) => command.type === 'SECTION') === false) {
-                sectionCommandParser.$applyToTaskJson({ type: 'SECTION', taskType: 'PROMPT_TASK' }, $taskJson, $pipelineJson);
-            }
-            // TODO [♓️] List commands and before apply order them to achieve order-agnostic commands
-            for (const { listItem, command } of commands) {
-                const commandParser = getParserForCommand(command);
-                if (commandParser.isUsedInPipelineTask !== true /* <- Note: [🦦][4] */) {
-                    throw new ParseError(spacetrim.spaceTrim((block) => `
-                            Command \`${command.type}\` is not allowed in the task of the promptbook ONLY at the pipeline head
-
-                            ${block(getPipelineIdentification())}
-                        `)); // <- TODO: [🚞]
-                }
-                try {
-                    commandParser.$applyToTaskJson(
-                    //            <- Note: [🦦] Its strange that this assertion must be here, [🦦][4] should do this assertion implicitly
-                    command, $taskJson, $pipelineJson);
-                }
-                catch (error) {
-                    if (!(error instanceof ParseError)) {
-                        throw error;
-                    }
-                    throw new ParseError(spacetrim.spaceTrim((block) => `
-                            Command \`${command.type}\` failed to apply to the task
-
-                            The error:
-                            ${block(error.message)}
+    }
+    /**
+     * Parses, applies, and persists one h2 task section.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function processPipelineSection(pipelineSection, $pipelineJson, getUniqueSectionName) {
+        const { $taskJson, language } = createTaskJsonFromSection(pipelineSection, getUniqueSectionName);
+        const commands = parsePipelineTaskCommands(pipelineSection.content);
+        applyDefaultTaskSectionType($taskJson, commands, $pipelineJson);
+        for (const commandItem of commands) {
+            applyPipelineTaskCommand(commandItem, $taskJson, $pipelineJson);
+        }
+        applyScriptTaskLanguage($taskJson, language, $pipelineJson);
+        registerTaskDependentParameters($taskJson, $pipelineJson);
+        persistTaskIfNeeded($taskJson, $pipelineJson);
+    }
+    /**
+     * Creates the mutable task JSON shell from one markdown section.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function createTaskJsonFromSection(pipelineSection, getUniqueSectionName) {
+        const { language, content } = extractOneBlockFromMarkdown(pipelineSection.content);
+        const normalizedLanguage = language || undefined;
+        const title = pipelineSection.title || DEFAULT_TASK_TITLE;
+        const $taskJson = {
+            isSectionTypeSet: false,
+            isTask: true,
+            taskType: undefined /* <- Note: [🍙] Putting here placeholder to keep `taskType` on top at final JSON */,
+            name: getUniqueSectionName(title),
+            title,
+            description: extractPipelineDescription(pipelineSection.content),
+            content,
+            // <- TODO: [🍙] Some standard order of properties
+        };
+        const resultingParameterName = extractResultingParameterName(pipelineSection.content);
+        if (resultingParameterName !== undefined) {
+            $taskJson.resultingParameterName = resultingParameterName;
+        }
+        return {
+            $taskJson,
+            language: normalizedLanguage,
+        };
+    }
+    /**
+     * Extracts the optional trailing `-> {parameter}` statement from a section body.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function extractResultingParameterName(sectionContent) {
+        var _a;
+        const lastLine = sectionContent.split(/\r?\n/).pop();
+        const resultingParameterNameMatch = RESULTING_PARAMETER_LINE_REGEXP.exec(lastLine);
+        return (_a = resultingParameterNameMatch === null || resultingParameterNameMatch === void 0 ? void 0 : resultingParameterNameMatch.groups) === null || _a === void 0 ? void 0 : _a.resultingParamName;
+    }
+    /**
+     * Parses all list-item commands declared inside one task section.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function parsePipelineTaskCommands(sectionContent) {
+        return extractAllListItemsFromMarkdown(sectionContent).map((listItem) => ({
+            listItem,
+            command: parseCommand(listItem, 'PIPELINE_TASK'),
+        }));
+    }
+    /**
+     * Applies the implicit default `PROMPT_TASK` section type when no SECTION command is present.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function applyDefaultTaskSectionType($taskJson, commands, $pipelineJson) {
+        const isSectionCommandPresent = commands.some(({ command }) => command.type === 'SECTION');
+        if (isSectionCommandPresent) {
+            return;
+        }
+        sectionCommandParser.$applyToTaskJson({ type: 'SECTION', taskType: 'PROMPT_TASK' }, $taskJson, $pipelineJson);
+    }
+    /**
+     * Parses and applies one command declared inside a task section.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function applyPipelineTaskCommand(commandItem, $taskJson, $pipelineJson) {
+        const { listItem, command } = commandItem;
+        const commandParser = getParserForCommand(command);
+        if (commandParser.isUsedInPipelineTask !== true /* <- Note: [🦦][4] */) {
+            throw new ParseError(spacetrim.spaceTrim((block) => `
+                    Command \`${command.type}\` is not allowed in the task of the promptbook ONLY at the pipeline head
 
-                            Current state of the task:
-                            ${block(JSON.stringify($taskJson, null, 4))}
+                    ${block(getPipelineIdentification($pipelineJson))}
+                `)); // <- TODO: [🚞]
+        }
+        try {
+            commandParser.$applyToTaskJson(command, $taskJson, $pipelineJson);
+            //             <- Note: [🦦] Its strange that this assertion must be here, [🦦][4] should do this assertion implicitly
+        }
+        catch (error) {
+            if (!(error instanceof ParseError)) {
+                throw error;
+            }
+            throw new ParseError(spacetrim.spaceTrim((block) => `
+                    Command \`${command.type}\` failed to apply to the task
 
-                            Command that failed to apply:
-                            ${block(JSON.stringify(command, null, 4))}
+                    The error:
+                    ${block(error.message)}
 
-                            *<- Maybe wrong order of commands in section?*
+                    Current state of the task:
+                    ${block(JSON.stringify($taskJson, null, 4))}
 
-                            Raw command:
-                            - ${listItem}
+                    Command that failed to apply:
+                    ${block(JSON.stringify(command, null, 4))}
 
-                            Usage of ${command.type}:
-                            ${block(commandParser.examples.map((example) => `- ${example}`).join('\n'))}
+                    *<- Maybe wrong order of commands in section?*
 
-                            ${block(getPipelineIdentification())}
-                      `)); // <- TODO: [🚞]
-                }
-                if (command.type === 'PARAMETER') {
-                    defineParam(command);
-                    // <- Note: [🍣]
-                }
-            }
-            // TODO: [🍧] Should be done in SECTION command
-            if ($taskJson.taskType === 'SCRIPT_TASK') {
-                if (!language) {
-                    throw new ParseError(spacetrim.spaceTrim((block) => `
-                            You must specify the language of the script in the \`SCRIPT\` task
+                    Raw command:
+                    - ${listItem}
 
-                            ${block(getPipelineIdentification())}
-                        `));
-                }
-                if (!SUPPORTED_SCRIPT_LANGUAGES.includes(language)) {
-                    throw new ParseError(spacetrim.spaceTrim((block) => `
-                            Script language ${language} is not supported.
+                    Usage of ${command.type}:
+                    ${block(commandParser.examples.map((example) => `- ${example}`).join('\n'))}
 
-                            Supported languages are:
-                            ${block(SUPPORTED_SCRIPT_LANGUAGES.join(', '))}
+                    ${block(getPipelineIdentification($pipelineJson))}
+              `)); // <- TODO: [🚞]
+        }
+        if (command.type === 'PARAMETER') {
+            defineParameter($pipelineJson, command);
+            // <- Note: [🍣]
+        }
+    }
+    /**
+     * Validates and stores the language for SCRIPT tasks.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function applyScriptTaskLanguage($taskJson, language, $pipelineJson) {
+        const isScriptTask = $taskJson.taskType === 'SCRIPT_TASK';
+        if (!isScriptTask) {
+            return;
+        }
+        if (!language) {
+            throw new ParseError(spacetrim.spaceTrim((block) => `
+                    You must specify the language of the script in the \`SCRIPT\` task
 
-                        `));
-                }
-                $taskJson.contentLanguage = language;
-            }
-            $taskJson.dependentParameterNames = Array.from(extractParameterNamesFromTask($taskJson));
-            for (const parameterName of $taskJson.dependentParameterNames) {
-                // TODO: [🧠] This definition should be made first in the task
-                defineParam({
-                    parameterName,
-                    parameterDescription: null,
-                    isInput: false,
-                    isOutput: false,
-                    // <- Note: In this case null+false+false means that we do not know yet if it is input or output and we will set it later
-                });
-            }
-            /*
-            // TODO: [🍧] This should be checked in `MODEL` command + better error message
-            if ($taskJson.taskType !== 'PROMPT_TASK' && $taskJson.modelRequirements !== undefined) {
-                throw new UnexpectedError(
-                    spaceTrim(
-                        (block) => `
-                            Model requirements are defined for the block type ${
-                                $taskJson.taskType
-                            } which is not a \`PROMPT\` task
+                    ${block(getPipelineIdentification($pipelineJson))}
+                `));
+        }
+        if (!SUPPORTED_SCRIPT_LANGUAGES.includes(language)) {
+            throw new ParseError(spacetrim.spaceTrim((block) => `
+                    Script language ${language} is not supported.
 
-                            This should be avoided by the \`modelCommandParser\`
+                    Supported languages are:
+                    ${block(SUPPORTED_SCRIPT_LANGUAGES.join(', '))}
 
-                            ${block(getPipelineIdentification())}
-                      `,
-                    ),
-                );
-            }
-            */
-            if ($taskJson.isTask) {
-                delete $taskJson.isSectionTypeSet;
-                delete $taskJson.isTask;
-                // TODO: [🍙] Maybe do reorder of `$taskJson` here
-                $pipelineJson.tasks.push($taskJson);
-            }
-        }
-        // =============================================================
-        // Note: 6️⃣ Mark parameters as INPUT if not explicitly set
-        if ($pipelineJson.parameters.every((parameter) => !parameter.isInput)) {
-            for (const parameter of $pipelineJson.parameters) {
-                const isThisParameterResulting = $pipelineJson.tasks.some((task) => task.resultingParameterName === parameter.name);
-                if (!isThisParameterResulting) {
-                    parameter.isInput = true;
-                    // <- TODO: [💔] Why this is making typescript error in vscode but not in cli
-                    //        > Type 'true' is not assignable to type 'false'.ts(2322)
-                    //        > (property) isInput: false
-                    //        > The parameter is input of the pipeline The parameter is NOT input of the pipeline
-                }
-            }
+                `));
         }
-        // =============================================================
-        // Note: 7️⃣ Mark all non-INPUT parameters as OUTPUT if any OUTPUT is not set
-        if ($pipelineJson.parameters.every((parameter) => !parameter.isOutput)) {
-            for (const parameter of $pipelineJson.parameters) {
-                if (!parameter.isInput) {
-                    parameter.isOutput = true;
-                    // <- TODO: [💔]
-                }
+        $taskJson.contentLanguage = language;
+    }
+    /**
+     * Extracts task dependencies and ensures referenced parameters exist.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function registerTaskDependentParameters($taskJson, $pipelineJson) {
+        $taskJson.dependentParameterNames = Array.from(extractParameterNamesFromTask($taskJson));
+        for (const parameterName of $taskJson.dependentParameterNames) {
+            // TODO: [🧠] This definition should be made first in the task
+            defineParameter($pipelineJson, {
+                parameterName,
+                parameterDescription: null,
+                isInput: false,
+                isOutput: false,
+                // <- Note: In this case null+false+false means that we do not know yet if it is input or output and we will set it later
+            });
+        }
+    }
+    /**
+     * Removes transient parsing flags and persists real tasks into the pipeline JSON.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function persistTaskIfNeeded($taskJson, $pipelineJson) {
+        /*
+        // TODO: [🍧] This should be checked in `MODEL` command + better error message
+        if ($taskJson.taskType !== 'PROMPT_TASK' && $taskJson.modelRequirements !== undefined) {
+            throw new UnexpectedError(
+                spaceTrim(
+                    (block) => `
+                        Model requirements are defined for the block type ${
+                            $taskJson.taskType
+                        } which is not a \`PROMPT\` task
+
+                        This should be avoided by the \`modelCommandParser\`
+
+                        ${block(getPipelineIdentification($pipelineJson))}
+                  `,
+                ),
+            );
+        }
+        */
+        if (!$taskJson.isTask) {
+            return;
+        }
+        delete $taskJson.isSectionTypeSet;
+        delete $taskJson.isTask;
+        // TODO: [🍙] Maybe do reorder of `$taskJson` here
+        $pipelineJson.tasks.push($taskJson);
+    }
+    /**
+     * Applies default INPUT/OUTPUT flags when the author did not specify them explicitly.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function applyImplicitParameterDirections($pipelineJson) {
+        markImplicitInputParameters($pipelineJson);
+        markImplicitOutputParameters($pipelineJson);
+    }
+    /**
+     * Marks non-result parameters as pipeline inputs when no input was declared.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function markImplicitInputParameters($pipelineJson) {
+        if ($pipelineJson.parameters.some((parameter) => parameter.isInput)) {
+            return;
+        }
+        for (const parameter of $pipelineJson.parameters) {
+            const isThisParameterResulting = $pipelineJson.tasks.some((task) => task.resultingParameterName === parameter.name);
+            if (!isThisParameterResulting) {
+                parameter.isInput = true;
+                // <- TODO: [💔] Why this is making typescript error in vscode but not in cli
+                //        > Type 'true' is not assignable to type 'false'.ts(2322)
+                //        > (property) isInput: false
+                //        > The parameter is input of the pipeline The parameter is NOT input of the pipeline
             }
         }
-        // =============================================================
-        // Note: 8️⃣ Cleanup of undefined values
-        $pipelineJson.tasks.forEach((tasks) => {
-            for (const [key, value] of Object.entries(tasks)) {
-                if (value === undefined) {
-                    delete tasks[key];
-                }
+    }
+    /**
+     * Marks every non-input parameter as output when no output was declared.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function markImplicitOutputParameters($pipelineJson) {
+        if ($pipelineJson.parameters.some((parameter) => parameter.isOutput)) {
+            return;
+        }
+        for (const parameter of $pipelineJson.parameters) {
+            if (!parameter.isInput) {
+                parameter.isOutput = true;
+                // <- TODO: [💔]
             }
-        });
-        $pipelineJson.parameters.forEach((parameter) => {
-            for (const [key, value] of Object.entries(parameter)) {
-                if (value === undefined) {
-                    delete parameter[key];
-                }
+        }
+    }
+    /**
+     * Removes `undefined` properties from serialized tasks and parameters.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function removeUndefinedValuesFromPipeline($pipelineJson) {
+        $pipelineJson.tasks.forEach(removeUndefinedProperties);
+        $pipelineJson.parameters.forEach(removeUndefinedProperties);
+    }
+    /**
+     * Deletes all own properties with `undefined` values from a mutable JSON entity.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function removeUndefinedProperties(entity) {
+        for (const [key, value] of Object.entries(entity)) {
+            if (value === undefined) {
+                delete entity[key];
             }
-        });
-        // =============================================================
-        // Note: 9️⃣ Apply sync high-level abstractions
+        }
+    }
+    /**
+     * Applies all sync-only high-level abstractions after parsing.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function applySyncHighLevelAbstractions($pipelineJson) {
         for (const highLevelAbstraction of HIGH_LEVEL_ABSTRACTIONS.filter(({ type }) => type === 'SYNC')) {
             highLevelAbstraction.$applyToPipelineJson($pipelineJson);
         }
-        // =============================================================
-        // Note: 🔟 Default formfactor
+    }
+    /**
+     * Ensures parsed pipelines always have the default `GENERIC` formfactor.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function ensurePipelineFormfactor($pipelineJson) {
         // Note: [🔆] If formfactor is still not set, set it to 'GENERIC'
         if ($pipelineJson.formfactorName === undefined) {
             $pipelineJson.formfactorName = 'GENERIC';
         }
-        // =============================================================
+    }
+    /**
+     * Finalizes ordering and exports the parsed pipeline JSON.
+     *
+     * @private internal utility of `parsePipeline`
+     */
+    function exportParsedPipelineJson($pipelineJson) {
         return exportJson({
             name: 'pipelineJson',
             message: `Result of \`parsePipeline\``,