@promptbook/components 0.100.0-24

package/esm/typings/src/commands/URL/urlCommandParser.d.ts

@@ -0,0 +1,9 @@
+import type { PipelineHeadCommandParser } from '../_common/types/CommandParser';
+import type { UrlCommand } from './UrlCommand';
+/**
+ * Parses the url command
+ *
+ * @see `documentationUrl` for more details
+ * @public exported from `@promptbook/editable`
+ */
+export declare const urlCommandParser: PipelineHeadCommandParser<UrlCommand>;

package/esm/typings/src/commands/X_ACTION/ActionCommand.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parsed ACTION command
+ *
+ * @see ./actionCommandParser.ts for more details
+ * @public exported from `@promptbook/editable`
+ */
+export type ActionCommand = {
+    readonly type: 'ACTION';
+};

package/esm/typings/src/commands/X_ACTION/actionCommand.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/commands/X_ACTION/actionCommandParser.d.ts

@@ -0,0 +1,12 @@
+import type { PipelineHeadCommandParser } from '../_common/types/CommandParser';
+import type { ActionCommand } from './ActionCommand';
+/**
+ * Parses the action command
+ *
+ * @see `documentationUrl` for more details
+ * @public exported from `@promptbook/editable`
+ */
+export declare const actionCommandParser: PipelineHeadCommandParser<ActionCommand>;
+/**
+ * Note: [⛱] There are two types of ACTION commands *...(read more in [⛱])*
+ */

package/esm/typings/src/commands/X_INSTRUMENT/InstrumentCommand.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parsed INSTRUMENT command
+ *
+ * @see ./instrumentCommandParser.ts for more details
+ * @public exported from `@promptbook/editable`
+ */
+export type InstrumentCommand = {
+    readonly type: 'INSTRUMENT';
+};

package/esm/typings/src/commands/X_INSTRUMENT/instrumentCommand.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/commands/X_INSTRUMENT/instrumentCommandParser.d.ts

@@ -0,0 +1,12 @@
+import type { PipelineHeadCommandParser } from '../_common/types/CommandParser';
+import type { InstrumentCommand } from './InstrumentCommand';
+/**
+ * Parses the instrument command
+ *
+ * @see `documentationUrl` for more details
+ * @public exported from `@promptbook/editable`
+ */
+export declare const instrumentCommandParser: PipelineHeadCommandParser<InstrumentCommand>;
+/**
+ * Note: [⛱] There are two types of INSTRUMENT commands *...(read more in [⛱])*
+ */

package/esm/typings/src/commands/_BOILERPLATE/BoilerplateCommand.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Parsed BOILERPLATE command
+ *
+ * @see ./boilerplateCommandParser.ts for more details
+ * @private within the commands folder
+ */
+export type BoilerplateCommand = {
+    readonly type: 'BOILERPLATE';
+    readonly value: string;
+};

package/esm/typings/src/commands/_BOILERPLATE/boilerplateCommand.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/commands/_BOILERPLATE/boilerplateCommandParser.d.ts

@@ -0,0 +1,11 @@
+import type { PipelineBothCommandParser } from '../_common/types/CommandParser';
+import type { BoilerplateCommand } from './BoilerplateCommand';
+/**
+ * Parses the boilerplate command
+ *
+ * Note: @@ This command is used as boilerplate for new commands - it should NOT be used in any `.book` file
+ *
+ * @see `documentationUrl` for more details
+ * @private within the commands folder
+ */
+export declare const boilerplateCommandParser: PipelineBothCommandParser<BoilerplateCommand>;

package/esm/typings/src/commands/_common/getParserForCommand.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from './types/Command';
+import type { CommandParser } from './types/CommandParser';
+/**
+ * Gets the parser for the command
+ *
+ * @returns the parser for the command
+ * @throws {UnexpectedError} if the parser is not found
+ *
+ * @public exported from `@promptbook/editable`
+ */
+export declare function getParserForCommand<TCommand extends Command>(command: TCommand): CommandParser<TCommand>;

package/esm/typings/src/commands/_common/getParserForCommand.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/commands/_common/parseCommand.d.ts

@@ -0,0 +1,12 @@
+import type { string_markdown_text } from '../../types/typeAliases';
+import type { Command } from './types/Command';
+import type { CommandUsagePlace } from './types/CommandUsagePlaces';
+/**
+ * Parses one line of ul/ol to command
+ *
+ * @returns parsed command object
+ * @throws {ParseError} if the command is invalid
+ *
+ * @public exported from `@promptbook/editable`
+ */
+export declare function parseCommand(raw: string_markdown_text, usagePlace: CommandUsagePlace): Command;

package/esm/typings/src/commands/_common/parseCommand.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/commands/_common/stringifyCommand.d.ts

@@ -0,0 +1,12 @@
+import type { string_markdown_text } from '../../types/typeAliases';
+import type { Command } from './types/Command';
+/**
+ * Stringifies the command
+ *
+ * @returns stringified command
+ * @throws {UnexpectedError} if the command is invalid
+ *
+ * @deprecated Option to convert JSON back to string is outdated and will be removed
+ * @private within the compilePipeline
+ */
+export declare function stringifyCommand(command: Command): string_markdown_text;

package/esm/typings/src/commands/_common/stringifyCommand.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/commands/_common/types/Command.d.ts

@@ -0,0 +1,6 @@
+import { COMMANDS } from '../../index';
+/**
+ * Command is one piece of the book file section which adds some logic to the task or the whole pipeline.
+ * It is parsed from the markdown from ul/ol items - one command per one item.
+ */
+export type Command = ReturnType<typeof COMMANDS[number]['parse']>;

package/esm/typings/src/commands/_common/types/CommandParser.d.ts

@@ -0,0 +1,205 @@
+import type { SetOptional, WritableDeep } from 'type-fest';
+import type { PipelineJson } from '../../../pipeline/PipelineJson/PipelineJson';
+import type { TaskJson } from '../../../pipeline/PipelineJson/TaskJson';
+import type { string_markdown_text } from '../../../types/typeAliases';
+import type { string_name } from '../../../types/typeAliases';
+import type { string_promptbook_documentation_url } from '../../../types/typeAliases';
+import type { string_SCREAMING_CASE } from '../../../utils/normalization/normalizeTo_SCREAMING_CASE';
+import type { ___and___ } from '../../../utils/organization/___and___';
+import type { CommandUsagePlace } from './CommandUsagePlaces';
+/**
+ * Base type for all command objects.
+ * Requires a `type` property which is a SCREAMING_CASE string.
+ *
+ * @private just abstract helper for command parsers
+ */
+export type CommandBase = {
+    type: string_name & string_SCREAMING_CASE;
+};
+/**
+ * Represents a parser for a specific command used within a Promptbook pipeline.
+ * It can parse commands used in the pipeline head, tasks, or both.
+ *
+ * @public exported from `@promptbook/editable`
+ */
+export type CommandParser<TCommand extends CommandBase> = PipelineHeadCommandParser<TCommand> | PipelineTaskCommandParser<TCommand> | PipelineBothCommandParser<TCommand>;
+/**
+ * Common properties shared by all command parsers.
+ *
+ * @private just abstract the common properties of the command parsers
+ */
+export type CommonCommandParser<TCommand extends CommandBase> = {
+    /**
+     * The unique SCREAMING_CASE name of the command (e.g., 'MODEL', 'PARAMETER').
+     */
+    readonly name: string_name & string_SCREAMING_CASE;
+    /**
+     * Indicates if the command can be used in the pipeline's head section.
+     */
+    readonly isUsedInPipelineHead: boolean;
+    /**
+     * Indicates if the command can be used within a pipeline task.
+     */
+    readonly isUsedInPipelineTask: boolean;
+    /**
+     * Optional alternative names (aliases) for the command, also in SCREAMING_CASE.
+     */
+    readonly aliasNames?: ReadonlyArray<string_name & string_SCREAMING_CASE>;
+    /**
+     * Optional list of deprecated names for the command, used for backward compatibility.
+     */
+    readonly deprecatedNames?: ReadonlyArray<string_name & string_SCREAMING_CASE>;
+    /**
+     * A brief description of the command's purpose, supporting simple Markdown.
+     */
+    readonly description: string_markdown_text;
+    /**
+     * A URL pointing to the command's documentation.
+     */
+    readonly documentationUrl: string_promptbook_documentation_url;
+    /**
+     * Examples demonstrating the usage of the command in Markdown format.
+     */
+    readonly examples: ReadonlyArray<string_markdown_text>;
+    /**
+     * @throws {ParseError} if the parsing fails
+     */
+    parse(input: CommandParserInput): TCommand;
+    /**
+     * Converts the command back to string
+     *
+     * Note: This is used in `pipelineJsonToString` utility
+     * @deprecated TODO: [🥍][🧠] Backup original files in `PipelineJson` same as in Promptbook.studio
+     */
+    stringify(command: TCommand): string_markdown_text;
+};
+/**
+ * Represents a command parser that can be used in both the pipeline head and tasks.
+ *
+ * @public exported from `@promptbook/editable`
+ */
+export type PipelineBothCommandParser<TCommand extends CommandBase> = ___and___ & Omit<PipelineHeadCommandParser<TCommand>, 'isUsedInPipelineTask'> & Omit<PipelineTaskCommandParser<TCommand>, 'isUsedInPipelineHead'>;
+/**
+ * Represents a command parser specifically for the pipeline head section.
+ *
+ * @public exported from `@promptbook/editable`
+ */
+export type PipelineHeadCommandParser<TCommand extends CommandBase> = CommonCommandParser<TCommand> & {
+    /**
+     * Always true for pipeline head commands.
+     */
+    readonly isUsedInPipelineHead: true;
+    /**
+     * Always false for pipeline head commands.
+     */
+    readonly isUsedInPipelineTask: false;
+    /**
+     * Apply the command to the `pipelineJson`
+     *
+     * Note: `$` is used to indicate that this function mutates given `pipelineJson`
+     */
+    $applyToPipelineJson(command: TCommand, $pipelineJson: $PipelineJson): void;
+    /**
+     * Reads the command from the `PipelineJson`
+     *
+     * Note: This is used in `pipelineJsonToString` utility
+     * @deprecated TODO: [🥍][🧠] Backup original files in `PipelineJson` same as in Promptbook.studio
+     */
+    takeFromPipelineJson(pipelineJson: PipelineJson): ReadonlyArray<TCommand>;
+};
+/**
+ * Represents a command parser specifically for pipeline tasks.
+ *
+ * @public exported from `@promptbook/editable`
+ */
+export type PipelineTaskCommandParser<TCommand extends CommandBase> = CommonCommandParser<TCommand> & {
+    /**
+     * Always false for pipeline task commands.
+     */
+    readonly isUsedInPipelineHead: false;
+    /**
+     * Always true for pipeline task commands.
+     */
+    readonly isUsedInPipelineTask: true;
+    /**
+     * Apply the command to the `pipelineJson`
+     *
+     * Note: `$` is used to indicate that this function mutates given `taskJson` and/or `pipelineJson`
+     */
+    $applyToTaskJson(command: TCommand, $taskJson: $TaskJson, $pipelineJson: $PipelineJson): void;
+    /**
+     * Reads the command from the `TaskJson`
+     *
+     * Note: This is used in `pipelineJsonToString` utility
+     */
+    takeFromTaskJson($taskJson: $TaskJson): ReadonlyArray<TCommand>;
+};
+/**
+ * Represents a mutable TaskJson object, used internally by command parsers during application.
+ *
+ * Note: `$` prefix indicates the object is intended for mutation.
+ *
+ * @private internal helper for command parsers
+ */
+export type $TaskJson = {
+    /**
+     * Flag indicating if the section type (e.g., `SIMPLE_TEMPLATE`) has been set for this task.
+     */
+    isSectionTypeSet: boolean;
+    /**
+     * Flag indicating if this object represents a task (as opposed to other sections like parameters).
+     */
+    isTask: boolean;
+} & Partial<WritableDeep<TaskJson>>;
+/**
+ * Represents a mutable PipelineJson object, used internally by command parsers during application.
+ *
+ * Note: `$` prefix indicates the object is intended for mutation.
+ *
+ * @private internal helper for command parsers
+ */
+export type $PipelineJson = WritableDeep<SetOptional<PipelineJson, 'formfactorName'>>;
+/**
+ * Input object provided to the `parse` method of a CommandParser.
+ */
+export type CommandParserInput = {
+    /**
+     * Specifies where the command is being used (pipeline head or task).
+     *
+     * @example 'PIPELINE_HEAD'
+     * @example 'PIPELINE_TASK'
+     */
+    readonly usagePlace: CommandUsagePlace;
+    /**
+     * The raw, unprocessed line containing the command and its arguments.
+     *
+     * @example 'promptbook version 0.62.0'
+     * @example 'FOREACH Text Line `{customers}` -> `{customer}`'
+     */
+    readonly raw: string_markdown_text;
+    /**
+     * The arguments part of the raw command line, after the command name.
+     *
+     * @example '0.62.0'
+     * @example 'List Line `{customers}` -> `{customer}`'
+     */
+    readonly rawArgs: string_markdown_text;
+    /**
+     * The normalized, SCREAMING_CASE representation of the command and its core arguments.
+     *
+     * @example 'PROMPTBOOK_ENGINE_VERSION_0_62_0'
+     * @example 'FOREACH_LIST_LINE_CUSTOMERS_CUSTOMER'
+     */
+    readonly normalized: string_name & string_SCREAMING_CASE;
+    /**
+     * An array of arguments extracted from the line where the command is used.
+     *
+     * @example [ '0.62.0' ]
+     * @example [ 'List', 'Line', '{customers}', '', '{customer}' ]
+     */
+    readonly args: Array<string_name>;
+};
+/**
+ * TODO: [♓️] Add order here
+ * TODO: [🧠][🍱] Maybe make some common abstraction between `HighLevelAbstraction` and `CommandParser`
+ */

package/esm/typings/src/commands/_common/types/CommandType.d.ts

@@ -0,0 +1,17 @@
+import type { Command } from './Command';
+/**
+ * Command is one piece of the book file section which adds some logic to the task or the whole pipeline.
+ * It is parsed from the markdown from ul/ol items - one command per one item.
+ *
+ * This is a type of the command like "KNOWLEDGE" or "PERSONA"
+ */
+export type CommandType = Command['type'];
+/**
+ * Command is one piece of the book file section which adds some logic to the task or the whole pipeline.
+ * It is parsed from the markdown from ul/ol items - one command per one item.
+ *
+ * This is a type of the command like "KNOWLEDGE" or "PERSONA"
+ *
+ex--rt type CommandTypeOrAlias = Command['type'] | Command['aliasNames'] | Command['deprecatedNames'];
+// <- TODO: [🧘] Implement
+*/

package/esm/typings/src/commands/_common/types/CommandUsagePlaces.d.ts

@@ -0,0 +1,13 @@
+import type { TupleToUnion } from 'type-fest';
+/**
+ * Where the command can be used
+ *
+ * @public exported from `@promptbook/editable`
+ */
+export type CommandUsagePlace = TupleToUnion<typeof CommandUsagePlaces>;
+/**
+ * Where the command can be used
+ *
+ * @private internal base for `CommandUsagePlace`
+ */
+export declare const CommandUsagePlaces: readonly ["PIPELINE_HEAD", "PIPELINE_TASK"];

package/esm/typings/src/commands/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * All available command parsers
+ *
+ * @public exported from `@promptbook/editable`
+ */
+export declare const COMMANDS: readonly [import("./_common/types/CommandParser").PipelineTaskCommandParser<import("./SECTION/SectionCommand").SectionCommand>, import("./_common/types/CommandParser").PipelineTaskCommandParser<import("./EXPECT/ExpectCommand").ExpectCommand>, import("./_common/types/CommandParser").PipelineTaskCommandParser<import("./FORMAT/FormatCommand").FormatCommand>, import("./_common/types/CommandParser").PipelineTaskCommandParser<import("./JOKER/JokerCommand").JokerCommand>, import("./_common/types/CommandParser").PipelineBothCommandParser<import("./MODEL/ModelCommand").ModelCommand>, import("./_common/types/CommandParser").PipelineBothCommandParser<import("./PARAMETER/ParameterCommand").ParameterCommand>, import("./_common/types/CommandParser").PipelineTaskCommandParser<import("./POSTPROCESS/PostprocessCommand").PostprocessCommand>, import("./_common/types/CommandParser").PipelineHeadCommandParser<import("./BOOK_VERSION/BookVersionCommand").BookVersionCommand>, import("./_common/types/CommandParser").PipelineHeadCommandParser<import("./FORMFACTOR/FormfactorCommand").FormfactorCommand>, import("./_common/types/CommandParser").PipelineHeadCommandParser<import("./URL/UrlCommand").UrlCommand>, import("./_common/types/CommandParser").PipelineHeadCommandParser<import("./KNOWLEDGE/KnowledgeCommand").KnowledgeCommand>, import("./_common/types/CommandParser").PipelineHeadCommandParser<import("./X_ACTION/ActionCommand").ActionCommand>, import("./_common/types/CommandParser").PipelineHeadCommandParser<import("./X_INSTRUMENT/InstrumentCommand").InstrumentCommand>, import("./_common/types/CommandParser").PipelineBothCommandParser<import("./PERSONA/PersonaCommand").PersonaCommand>, import("./_common/types/CommandParser").PipelineTaskCommandParser<import("./FOREACH/ForeachCommand").ForeachCommand>, import("./_common/types/CommandParser").PipelineBothCommandParser<import("./_BOILERPLATE/BoilerplateCommand").BoilerplateCommand>];
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */