@promptbook/cli 0.113.0-8 → 0.114.0-0

package/src/cli/cli-commands/common/harness/formatHarnessInstallationWarning.ts

@@ -0,0 +1,28 @@
+import { spaceTrim } from 'spacetrim';
+import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
+
+/**
+ * Formats the warning shown when a harness is missing or outdated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function formatHarnessInstallationWarning(status: HarnessInstallationStatus): string {
+    const { definition, installedVersion, latestVersion } = status;
+
+    if (status.installationState === 'not-installed') {
+        return spaceTrim(`
+            **${definition.label}** is not installed globally.
+
+            The \`${definition.commandName}\` command was not found, so the \`${definition.harnessName}\` harness cannot run.
+        `);
+    }
+
+    return spaceTrim(`
+        **${definition.label}** is outdated.
+
+        Installed version: \`${installedVersion}\`
+        Newest version: \`${latestVersion}\`
+    `);
+}
+
+// Note: [🟡] Code for CLI harness installation warning [formatHarnessInstallationWarning](src/cli/cli-commands/common/harness/formatHarnessInstallationWarning.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/harness/isHarnessVersionOutdated.ts

@@ -0,0 +1,39 @@
+/**
+ * Compares the installed harness version with the newest version published to npm.
+ *
+ * Only the numeric `major.minor.patch` segments are compared and pre-release suffixes are ignored,
+ * so a harness installed from a pre-release build of the newest version is not reported as outdated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function isHarnessVersionOutdated(installedVersion: string, latestVersion: string): boolean {
+    const installedSegments = parseVersionSegments(installedVersion);
+    const latestSegments = parseVersionSegments(latestVersion);
+    const segmentCount = Math.max(installedSegments.length, latestSegments.length);
+
+    for (let segmentIndex = 0; segmentIndex < segmentCount; segmentIndex++) {
+        const installedSegment = installedSegments[segmentIndex] ?? 0;
+        const latestSegment = latestSegments[segmentIndex] ?? 0;
+
+        if (installedSegment !== latestSegment) {
+            return installedSegment < latestSegment;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Splits one version into its numeric segments, dropping the pre-release and build suffix.
+ */
+function parseVersionSegments(version: string): ReadonlyArray<number> {
+    const [numericVersion = ''] = version.trim().split(/[-+]/u);
+
+    return numericVersion.split('.').map((segment) => {
+        const segmentNumber = Number.parseInt(segment, 10);
+
+        return Number.isNaN(segmentNumber) ? 0 : segmentNumber;
+    });
+}
+
+// Note: [🟡] Code for CLI harness version comparison [isHarnessVersionOutdated](src/cli/cli-commands/common/harness/isHarnessVersionOutdated.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/promptRunnerCliOptions.ts

@@ -4,14 +4,14 @@ import {
     Option,
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
-import type { ThinkingLevel } from '../coder/ThinkingLevel';
-import { THINKING_LEVEL_VALUES } from '../coder/ThinkingLevel';
 import {
     CLI_AGENT_HARNESS_NAMES,
     PTBK_HARNESS_ENV,
     PTBK_MODEL_ENV,
     PTBK_THINKING_LEVEL_ENV,
 } from '../../../book-3.0/cliAgentEnv';
+import type { ThinkingLevel } from '../coder/ThinkingLevel';
+import { THINKING_LEVEL_VALUES } from '../coder/ThinkingLevel';
 
 export { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV };
 

package/src/cli/cli-commands/make.ts

@@ -23,8 +23,8 @@ import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
 import { $provideFilesystemForNode } from '../../scrapers/_common/register/$provideFilesystemForNode';
 import { $provideScrapersForNode } from '../../scrapers/_common/register/$provideScrapersForNode';
 import { $provideScriptingForNode } from '../../scrapers/_common/register/$provideScriptingForNode';
-import type { string_file_extension } from '../../types/string_sha256';
 import type { string_promptbook_server_url } from '../../types/string_promptbook_server_url';
+import type { string_file_extension } from '../../types/string_sha256';
 import { stringifyPipelineJson } from '../../utils/editable/utils/stringifyPipelineJson';
 import type { $side_effect } from '../../utils/organization/$side_effect';
 import { keepTypeImported } from '../../utils/organization/keepTypeImported';

package/src/cli/cli-commands/run/runCommandAction.ts

@@ -1,8 +1,8 @@
 import colors from 'colors';
+import { jsonParse } from '../../../formats/json/utils/jsonParse';
 import type { PipelineJson } from '../../../pipeline/PipelineJson/PipelineJson';
 import type { PrepareAndScrapeOptions } from '../../../prepare/PrepareAndScrapeOptions';
 import type { string_parameter_name, string_parameter_value } from '../../../types/string_name';
-import { jsonParse } from '../../../formats/json/utils/jsonParse';
 import { normalizeToKebabCase } from '../../../utils/normalization/normalize-to-kebab-case';
 import { runInteractiveChatbot } from '../runInteractiveChatbot';
 import { prepareRunCommandResources } from './prepareRunCommandResources';

package/src/collection/agent-collection/CreateAgentInput.ts

@@ -1,9 +1,6 @@
+import type { AgentVisibility } from '../../book-2.0/agent-source/agentSourceVisibility';
+import { AGENT_VISIBILITY_VALUES, normalizeAgentVisibility } from '../../book-2.0/agent-source/agentSourceVisibility';
 import type { string_book } from '../../book-2.0/agent-source/string_book';
-import {
-    AGENT_VISIBILITY_VALUES,
-    normalizeAgentVisibility,
-    type AgentVisibility,
-} from '../../book-2.0/agent-source/agentSourceVisibility';
 import { LimitReachedError } from '../../errors/LimitReachedError';
 import { ParseError } from '../../errors/ParseError';
 import type { LlmToolDefinition } from '../../types/LlmToolDefinition';

package/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase.ts

@@ -12,6 +12,7 @@ import { $randomBase58 } from '../../../../utils/random/$randomBase58';
 import { PROMPTBOOK_ENGINE_VERSION } from '../../../../version';
 import type { AgentCollectionInSupabaseOptions } from './AgentCollectionInSupabaseOptions';
 import type { AgentsDatabaseSchema } from './AgentsDatabaseSchema';
+import { buildAgentNameOrPermanentIdFilter } from './buildAgentNameOrPermanentIdFilter';
 import type { CreateAgentPersistenceRecordsOptions } from './createAgentPersistenceRecords';
 import { createAgentPersistenceRecords } from './createAgentPersistenceRecords';
 import { prepareAgentSourceForPersistence } from './prepareAgentSourceForPersistence';
@@ -49,19 +50,6 @@ function normalizeHistoryVersionName(versionName: string | null | undefined): st
     return normalizedVersionName.length > 0 ? normalizedVersionName : null;
 }
 
-/**
- * Builds a Supabase `.or()` filter for agent name or permanent id lookups.
- *
- * @param agentNameOrPermanentId - Agent name or stable permanent identifier to match.
- * @returns `.or()` filter string safe to pass to Supabase.
- *
- * @private internal helper of `AgentCollectionInSupabase`
- */
-function buildAgentNameOrPermanentIdFilter(agentNameOrPermanentId: string): string {
-    const encodedAgentIdentifier = encodeURIComponent(agentNameOrPermanentId);
-    return `agentName.eq.${encodedAgentIdentifier},permanentId.eq.${encodedAgentIdentifier}`;
-}
-
 /**
  * One saved Agent history row without the full source payload.
  */

package/src/collection/agent-collection/constructors/agent-collection-in-supabase/buildAgentNameOrPermanentIdFilter.ts

@@ -0,0 +1,38 @@
+/**
+ * Escapes SQL `LIKE`/`ILIKE` wildcard characters so that a value is matched literally.
+ *
+ * The escape character `\` itself, the multi-character wildcard `%` and the single-character
+ * wildcard `_` are prefixed with a backslash. This turns a case-insensitive `ilike` lookup into
+ * an exact (but still case-insensitive) match instead of an unintended pattern match.
+ *
+ * @param value - Raw value that will be embedded into an `ilike` pattern.
+ * @returns Value with every `LIKE` special character escaped.
+ *
+ * @private internal helper of `buildAgentNameOrPermanentIdFilter`
+ */
+function escapeLikePattern(value: string): string {
+    return value.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
+}
+
+/**
+ * Builds a Supabase `.or()` filter that matches an agent by its human-readable name or its permanent id.
+ *
+ * The human-readable `agentName` is matched exactly, while the `permanentId` is matched
+ * case-insensitively (via `ilike`) so that the same permanent id resolves to the same agent
+ * regardless of the letter casing used in the URL.
+ *
+ * Supabase/PostgREST filters expect values to be URL-encoded so that characters like spaces or
+ * punctuation do not break the query syntax (e.g. `agentName.eq.AI Team`). The permanent-id value is
+ * additionally `LIKE`-escaped so that a name containing wildcard characters cannot be interpreted as
+ * a pattern.
+ *
+ * @param agentNameOrPermanentId - Agent name or stable permanent identifier to match.
+ * @returns `.or()` filter string safe to pass to Supabase.
+ *
+ * @private internal helper shared by `AgentCollectionInSupabase` and the Agents Server agent lookups
+ */
+export function buildAgentNameOrPermanentIdFilter(agentNameOrPermanentId: string): string {
+    const encodedAgentName = encodeURIComponent(agentNameOrPermanentId);
+    const encodedPermanentId = encodeURIComponent(escapeLikePattern(agentNameOrPermanentId));
+    return `agentName.eq.${encodedAgentName},permanentId.ilike.${encodedPermanentId}`;
+}

package/src/collection/agent-collection/constructors/agent-collection-in-supabase/prepareAgentSourceForPersistence.ts

@@ -1,9 +1,9 @@
 import type { AgentBasicInformation } from '../../../../book-2.0/agent-source/AgentBasicInformation';
+import type { AgentVisibility } from '../../../../book-2.0/agent-source/agentSourceVisibility';
 import {
     DEFAULT_AGENT_VISIBILITY,
     parseAgentSourceVisibility,
     setAgentSourceVisibility,
-    type AgentVisibility,
 } from '../../../../book-2.0/agent-source/agentSourceVisibility';
 import { parseAgentSource } from '../../../../book-2.0/agent-source/parseAgentSource';
 import type { string_book } from '../../../../book-2.0/agent-source/string_book';

package/src/commitments/META/META.ts

@@ -7,13 +7,14 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
  * META commitment definition
  *
  * The META commitment handles all meta-information about the agent such as:
- * - META AVATAR: Sets the agent's built-in default avatar visual
+ * - META AVATAR / META VISUAL: Sets the agent's built-in default avatar visual
  * - META IMAGE: Sets the agent's avatar/profile image URL
  * - META LINK: Provides profile/source links for the person the agent models
  * - META DOMAIN: Sets the canonical custom domain/host of the agent
  * - META TITLE: Sets the agent's display title
  * - META DESCRIPTION: Sets the agent's description
  * - META INPUT PLACEHOLDER: Sets chat input placeholder text
+ * - META THINKING MESSAGE: Adds custom thinking placeholder variants
  * - META [ANYTHING]: Any other meta information in uppercase format
  *
  * These commitments are special because they don't affect the system message,
@@ -22,13 +23,14 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
  * Example usage in agent source:
  *
  * ```book
- * META AVATAR pixel-art
+ * META VISUAL pixel-art
  * META IMAGE https://example.com/avatar.jpg
  * META LINK https://twitter.com/username
  * META DOMAIN my-agent.com
  * META TITLE Professional Assistant
  * META DESCRIPTION An AI assistant specialized in business tasks
  * META INPUT PLACEHOLDER Write a message...
+ * META THINKING MESSAGE Thinking...
  * META AUTHOR John Doe
  * META VERSION 1.0
  * ```
@@ -65,13 +67,14 @@ export class MetaCommitmentDefinition extends BaseCommitmentDefinition<`META${st
 
             ## Supported META types
 
-            - **META AVATAR** - Sets the agent's built-in default avatar visual
+            - **META AVATAR** / **META VISUAL** - Sets the agent's built-in default avatar visual
             - **META IMAGE** - Sets the agent's avatar/profile image URL
             - **META LINK** - Provides profile/source links for the person the agent models
             - **META DOMAIN** - Sets the canonical custom domain/host of the agent
             - **META TITLE** - Sets the agent's display title
             - **META DESCRIPTION** - Sets the agent's description
             - **META INPUT PLACEHOLDER** - Sets chat input placeholder text
+            - **META THINKING MESSAGE** - Adds custom thinking placeholder variants
             - **META [ANYTHING]** - Any other meta information in uppercase format
 
             ## Key aspects
@@ -80,6 +83,7 @@ export class MetaCommitmentDefinition extends BaseCommitmentDefinition<`META${st
             - Used for visual representation and attribution in user interfaces
             - Multiple META commitments of different types can be used
             - Multiple META LINK commitments can be used for different social profiles
+            - Multiple META THINKING MESSAGE commitments can be used for different thinking placeholder variants
             - If multiple META commitments of the same type are specified, the last one takes precedence (except for LINK)
 
             ## Examples
@@ -89,7 +93,7 @@ export class MetaCommitmentDefinition extends BaseCommitmentDefinition<`META${st
             \`\`\`book
             Professional Assistant
 
-            META AVATAR octopus3
+            META VISUAL octopus3
             META IMAGE https://example.com/professional-avatar.jpg
             META TITLE Senior Business Consultant
             META DESCRIPTION Specialized in strategic planning and project management

package/src/commitments/META_AVATAR/META_AVATAR.ts

@@ -4,17 +4,22 @@ import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentMo
 import { TODO_USE } from '../../utils/organization/TODO_USE';
 import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 
+/**
+ * META AVATAR / META VISUAL commitment type.
+ */
+type MetaAvatarCommitmentType = 'META AVATAR' | 'META VISUAL';
+
 /**
  * META AVATAR commitment definition
  *
- * The `META AVATAR` commitment sets the built-in default avatar visual used when
- * the agent does not provide an explicit `META IMAGE`.
+ * The `META AVATAR` and `META VISUAL` commitments set the built-in default avatar visual
+ * used when the agent does not provide an explicit `META IMAGE`.
  *
  * @private [🪔] Maybe export the commitments through some package
  */
-export class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition<'META AVATAR'> {
-    public constructor() {
-        super('META AVATAR');
+export class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition<MetaAvatarCommitmentType> {
+    public constructor(type: MetaAvatarCommitmentType = 'META AVATAR') {
+        super(type);
     }
 
     /**
@@ -38,14 +43,15 @@ export class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition<'ME
         const supportedVisuals = AVATAR_VISUALS.map((avatarVisual) => `\`${avatarVisual.id}\``).join(', ');
 
         return spaceTrim(`
-            # META AVATAR
+            # ${this.type}
 
             Sets the built-in avatar visual used for the agent when no explicit \`META IMAGE\` is provided.
+            \`META AVATAR\` and \`META VISUAL\` are equivalent.
 
             ## Key aspects
 
             - Does not modify the agent's behavior or responses.
-            - Only one \`META AVATAR\` should be used per agent.
+            - Only one \`META AVATAR\` or \`META VISUAL\` should be used per agent.
             - If multiple are specified, the last one takes precedence.
             - Values are matched case-insensitively and spaces, hyphens, and underscores are normalized.
             - Supported visuals are derived from the shared avatar registry: ${supportedVisuals}.
@@ -60,9 +66,9 @@ export class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition<'ME
             \`\`\`
 
             \`\`\`book
-            Orb Assistant
+            Minecraft Assistant
 
-            META AVATAR orb
+            META VISUAL Minecraft2
             GOAL Answer in a calm and focused way.
             \`\`\`
         `);
@@ -71,7 +77,7 @@ export class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition<'ME
     applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements {
         TODO_USE(content);
 
-        // META AVATAR doesn't modify the system message or model requirements.
+        // META AVATAR and META VISUAL don't modify the system message or model requirements.
         // It's handled separately in the parsing logic for profile avatar resolution.
         return requirements;
     }

package/src/commitments/META_THINKING_MESSAGE/META_THINKING_MESSAGE.ts

@@ -0,0 +1,76 @@
+import { spaceTrim } from 'spacetrim';
+import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
+import { TODO_USE } from '../../utils/organization/TODO_USE';
+import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
+
+/**
+ * META THINKING MESSAGE commitment definition.
+ *
+ * The `META THINKING MESSAGE` commitment adds one custom thinking placeholder
+ * variant used by chat UIs while an agent is composing a reply.
+ *
+ * @private Metadata-only commitment used by Agents Server chat UIs.
+ */
+export class MetaThinkingMessageCommitmentDefinition extends BaseCommitmentDefinition<'META THINKING MESSAGE'> {
+    public constructor() {
+        super('META THINKING MESSAGE');
+    }
+
+    /**
+     * Short one-line description of META THINKING MESSAGE.
+     */
+    get description(): string {
+        return 'Add a custom thinking placeholder shown while the agent replies.';
+    }
+
+    /**
+     * Icon for this commitment.
+     */
+    get icon(): string {
+        return '💭';
+    }
+
+    /**
+     * Markdown documentation for META THINKING MESSAGE commitment.
+     */
+    get documentation(): string {
+        return spaceTrim(`
+            # META THINKING MESSAGE
+
+            Adds one custom placeholder variant shown while the agent is composing a reply.
+
+            ## Key aspects
+
+            - Does not modify model behavior, system message, or tools.
+            - Multiple \`META THINKING MESSAGE\` commitments define multiple variants.
+            - Chat UIs randomly rotate between the configured variants while the reply is running.
+            - When no non-empty variants are configured, the server-level \`THINKING_MESSAGES\` metadata is used.
+            - Supports multiline markdown content.
+
+            ## Example
+
+            \`\`\`book
+            Helpful Assistant
+
+            META THINKING MESSAGE Thinking...
+            META THINKING MESSAGE Processing...
+            META THINKING MESSAGE
+
+            Doing
+            extra **hard** work
+            \`\`\`
+        `);
+    }
+
+    public applyToAgentModelRequirements(
+        requirements: AgentModelRequirements,
+        content: string,
+    ): AgentModelRequirements {
+        TODO_USE(content);
+
+        // META THINKING MESSAGE is metadata only and does not alter model requirements.
+        return requirements;
+    }
+}
+
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/commitments/USE_BROWSER/USE_BROWSER.ts

@@ -72,6 +72,7 @@ export class UseBrowserCommitmentDefinition extends BaseCommitmentDefinition<'US
               1. **One-shot URL fetching**: Simple function to fetch and scrape URL content (active)
               2. **Running browser**: For complex tasks like scrolling, clicking, form filling, etc. (runtime-dependent)
             - The actual browser tool usage is handled by the agent runtime
+            - On the Agents Server, every agent browses in its own persistent isolated browser profile, so cookies and logged-in sessions survive across chats (the profile is linked from the agent wallet)
             - Allows the agent to fetch current information from websites and documents
             - Useful for research tasks, fact-checking, and accessing dynamic content
             - Supports various content types including HTML pages and PDF documents

package/src/commitments/index.ts

@@ -28,6 +28,7 @@ import { MetaFontCommitmentDefinition } from './META_FONT/META_FONT';
 import { MetaImageCommitmentDefinition } from './META_IMAGE/META_IMAGE';
 import { MetaInputPlaceholderCommitmentDefinition } from './META_INPUT_PLACEHOLDER/META_INPUT_PLACEHOLDER';
 import { MetaLinkCommitmentDefinition } from './META_LINK/META_LINK';
+import { MetaThinkingMessageCommitmentDefinition } from './META_THINKING_MESSAGE/META_THINKING_MESSAGE';
 import { MetaVisibilityCommitmentDefinition } from './META_VISIBILITY/META_VISIBILITY';
 import { MetaVoiceCommitmentDefinition } from './META_VOICE/META_VOICE';
 import { ModelCommitmentDefinition } from './MODEL/MODEL';
@@ -96,6 +97,7 @@ export const COMMITMENT_REGISTRY = [
     new ActionCommitmentDefinition('ACTIONS'),
     new ComponentCommitmentDefinition(),
     new MetaAvatarCommitmentDefinition(),
+    new MetaAvatarCommitmentDefinition('META VISUAL'),
     new MetaImageCommitmentDefinition(),
     new MetaColorCommitmentDefinition(),
     new MetaFontCommitmentDefinition(),
@@ -103,6 +105,7 @@ export const COMMITMENT_REGISTRY = [
     new MetaDomainCommitmentDefinition(),
     new MetaDisclaimerCommitmentDefinition(),
     new MetaInputPlaceholderCommitmentDefinition(),
+    new MetaThinkingMessageCommitmentDefinition(),
     new MetaVisibilityCommitmentDefinition(),
     new MetaCommitmentDefinition(),
     new MetaVoiceCommitmentDefinition(),

package/src/conversion/parsePipeline/applyPipelineHead.ts

@@ -4,10 +4,10 @@ import { parseCommand } from '../../commands/_common/parseCommand';
 import type { $PipelineJson, CommandBase, PipelineHeadCommandParser } from '../../commands/_common/types/CommandParser';
 import { ParseError } from '../../errors/ParseError';
 import { extractAllListItemsFromMarkdown } from '../../utils/markdown/extractAllListItemsFromMarkdown';
+import type { MarkdownSection } from '../../utils/markdown/parseMarkdownSection';
 import { defineParameter } from './defineParameter';
 import { extractPipelineDescription } from './extractPipelineDescription';
 import { getPipelineIdentification } from './getPipelineIdentification';
-import type { MarkdownSection } from '../../utils/markdown/parseMarkdownSection';
 
 /**
  * Applies the pipeline head title, description, and head-level commands.

package/src/conversion/parsePipeline/createUniqueSectionNameResolver.ts

@@ -1,7 +1,7 @@
 import type { number_integer, number_positive } from '../../types/number_positive';
 import type { string_name } from '../../types/string_name';
-import { titleToName } from '../../utils/normalization/titleToName';
 import type { MarkdownSection } from '../../utils/markdown/parseMarkdownSection';
+import { titleToName } from '../../utils/normalization/titleToName';
 
 /**
  * Resolves a unique task name for one parsed markdown section title.

package/src/conversion/parsePipeline/processPipelineSection.ts

@@ -13,8 +13,8 @@ import { DEFAULT_TASK_TITLE } from '../../config';
 import { ParseError } from '../../errors/ParseError';
 import type { ScriptTaskJson } from '../../pipeline/PipelineJson/ScriptTaskJson';
 import type { TaskJson } from '../../pipeline/PipelineJson/TaskJson';
-import { SUPPORTED_SCRIPT_LANGUAGES } from '../../types/ScriptLanguage';
 import type { ScriptLanguage } from '../../types/ScriptLanguage';
+import { SUPPORTED_SCRIPT_LANGUAGES } from '../../types/ScriptLanguage';
 import { extractAllListItemsFromMarkdown } from '../../utils/markdown/extractAllListItemsFromMarkdown';
 import { extractOneBlockFromMarkdown } from '../../utils/markdown/extractOneBlockFromMarkdown';
 import type { MarkdownSection } from '../../utils/markdown/parseMarkdownSection';

package/src/conversion/validation/validatePipeline/createPipelineValidationContext.ts

@@ -0,0 +1,43 @@
+import type { PipelineJson } from '../../../pipeline/PipelineJson/PipelineJson';
+
+/**
+ * Shared validation context for one pipeline validation pass.
+ *
+ * @private type of `validatePipeline`
+ */
+export type PipelineValidationContext = {
+    pipeline: PipelineJson;
+    pipelineIdentification: string;
+};
+
+/**
+ * Creates the shared validation context for one pipeline.
+ *
+ * @private function of `validatePipeline`
+ */
+export function createPipelineValidationContext(pipeline: PipelineJson): PipelineValidationContext {
+    return {
+        pipeline,
+        pipelineIdentification: getPipelineIdentification(pipeline),
+    };
+}
+
+/**
+ * Builds a short file/url identification block for validation errors.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function getPipelineIdentification(pipeline: Pick<PipelineJson, 'sourceFile' | 'pipelineUrl'>): string {
+    // Note: This is a 😐 implementation of [🚞]
+    const pipelineIdentificationParts: Array<string> = [];
+
+    if (pipeline.sourceFile !== undefined) {
+        pipelineIdentificationParts.push(`File: ${pipeline.sourceFile}`);
+    }
+
+    if (pipeline.pipelineUrl !== undefined) {
+        pipelineIdentificationParts.push(`Url: ${pipeline.pipelineUrl}`);
+    }
+
+    return pipelineIdentificationParts.join('\n');
+}

package/src/conversion/validation/validatePipeline/validatePipelineCollectionsStructure.ts

@@ -0,0 +1,72 @@
+import { spaceTrim } from 'spacetrim';
+import { ParseError } from '../../../errors/ParseError';
+import type { PipelineJson } from '../../../pipeline/PipelineJson/PipelineJson';
+import type { PipelineValidationContext } from './createPipelineValidationContext';
+
+/**
+ * Validates that the expected top-level collections have array structure.
+ *
+ * @private function of `validatePipeline`
+ */
+export function validatePipelineCollectionsStructure({
+    pipeline,
+    pipelineIdentification,
+}: PipelineValidationContext): void {
+    validatePipelineParametersCollection(pipeline, pipelineIdentification);
+    validatePipelineTasksCollection(pipeline, pipelineIdentification);
+}
+
+/**
+ * Validates that `pipeline.parameters` is an array.
+ *
+ * @private internal utility of `validatePipelineCollectionsStructure`
+ */
+function validatePipelineParametersCollection(
+    pipeline: Pick<PipelineJson, 'parameters'>,
+    pipelineIdentification: string,
+): void {
+    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
+    if (Array.isArray(pipeline.parameters)) {
+        return;
+    }
+
+    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
+    throw new ParseError(
+        spaceTrim(
+            (block) => `
+                Pipeline is valid JSON but with wrong structure
+
+                \`PipelineJson.parameters\` expected to be an array, but got ${typeof pipeline.parameters}
+
+                ${block(pipelineIdentification)}
+            `,
+        ),
+        // <- TODO: [🚞]
+    );
+}
+
+/**
+ * Validates that `pipeline.tasks` is an array.
+ *
+ * @private internal utility of `validatePipelineCollectionsStructure`
+ */
+function validatePipelineTasksCollection(pipeline: Pick<PipelineJson, 'tasks'>, pipelineIdentification: string): void {
+    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
+    if (Array.isArray(pipeline.tasks)) {
+        return;
+    }
+
+    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
+    throw new ParseError(
+        spaceTrim(
+            (block) => `
+                Pipeline is valid JSON but with wrong structure
+
+                \`PipelineJson.tasks\` expected to be an array, but got ${typeof pipeline.tasks}
+
+                ${block(pipelineIdentification)}
+            `,
+        ),
+        // <- TODO: [🚞]
+    );
+}