pupt-lib 1.2.5 → 1.3.0

package/dist/index.d.ts

@@ -1,29 +1,458 @@
-export declare const VERSION = "0.0.0-development";
-export { TYPE, PROPS, CHILDREN, DEFERRED_REF } from './types/symbols';
-export { isPuptElement, isDeferredRef } from './types/element';
-export type { PuptNode, PuptElement, ComponentType, DeferredRef, LlmConfig, LlmProvider, OutputConfig, CodeConfig, UserConfig, RuntimeConfig, EnvironmentContext, RenderContext, RenderOptions, RenderResult, RenderSuccess, RenderFailure, RenderError, RenderMetadata, PostExecutionAction, InputRequirement, ValidationResult, ValidationError, ValidationWarning, CollectedInputs, ComponentProps, PromptProps, StructuralProps, CommonProps, SearchablePrompt, SearchOptions, SearchResult, SearchResultMatch, SearchEngineConfig, PuptConfig, PuptLibrary, DiscoveredPrompt, LibraryLoadResult, PuptInitConfig, } from './types';
-export { LLM_PROVIDERS, inferProviderFromModel, DEFAULT_ENVIRONMENT, createEnvironment, createRuntimeConfig, ensureRuntimeCacheReady, } from './types';
-export { Component, isComponentClass, COMPONENT_MARKER } from './component';
-export { render } from './render';
-export { createInputIterator } from './services/input-iterator';
-export type { InputIterator, InputIteratorOptions, OnMissingDefaultStrategy } from './services/input-iterator';
-export { evaluateFormula } from './services/formula-parser';
-export { Transformer } from './services/transformer';
-export { evaluateModule } from './services/module-evaluator';
-export type { EvaluateOptions } from './services/module-evaluator';
-export { preprocessSource, isPromptFile, needsPreprocessing, BUILTIN_COMPONENTS } from './services/preprocessor';
-export type { PreprocessOptions } from './services/preprocessor';
-export { ModuleLoader } from './services/module-loader';
-export type { SourceType, LoadedLibrary, ParsedPackageSource } from './services/module-loader';
-export { resolveCdn, generateImportMap, serializeImportMap, generateImportMapScript, generatePuptLibImportMap, generatePuptLibImportMapScript, } from './services/browser-support';
-export type { CdnProvider, CdnOptions, Dependency, ImportMap, PuptLibImportMapOptions, } from './services/browser-support';
-export * from './components';
-export { createPromptFromSource, createPrompt } from './create-prompt';
-export type { CreatePromptOptions } from './create-prompt';
-export { Pupt } from './api';
-export type { DiscoveredPromptWithMethods } from './api';
-export { createSearchEngine } from './services/search-engine';
-export type { SearchEngine } from './services/search-engine';
-export { FileSearchEngine, createFileSearchEngine } from './services/file-search-engine';
-export type { FileInfo, FileSearchResult, FileSearchEngineConfig, } from './services/file-search-engine';
-//# sourceMappingURL=index.d.ts.map
+import { z } from 'zod';
+import { ZodObject } from 'zod';
+import { ZodRawShape } from 'zod';
+
+/** Symbol for element children */
+declare const CHILDREN: unique symbol;
+
+/**
+ * Abstract base class for pupt-lib components.
+ * Extend this class to create class-based components with access to render context.
+ *
+ * Components can implement:
+ * - `resolve()` only: Compute a value (rendered as string, no visual output)
+ * - `render()` only: Produce visual output (backward compatible)
+ * - Both `resolve()` and `render()`: Compute value, then render with that value
+ *
+ * Both resolve and render methods can be synchronous or asynchronous.
+ *
+ * @example
+ * ```typescript
+ * // Component with resolve() only - value is stringified
+ * class ValueComponent extends Component<{ value: string }, string> {
+ *   resolve(props: { value: string }) {
+ *     return props.value.toUpperCase();
+ *   }
+ * }
+ *
+ * // Component with only render() (backward compatible)
+ * class Greeting extends Component<{ name: string }> {
+ *   render(props: { name: string }) {
+ *     return `Hello, ${props.name}!`;
+ *   }
+ * }
+ *
+ * // Component with both resolve() and render()
+ * class DataFetcher extends Component<{ id: number }, { data: string }> {
+ *   resolve(props: { id: number }) {
+ *     return { data: `Data for ${props.id}` };
+ *   }
+ *   render(props: { id: number }, value: { data: string }) {
+ *     return `Fetched: ${value.data}`;
+ *   }
+ * }
+ * ```
+ */
+declare abstract class Component<Props = Record<string, unknown>, ResolveType = void> {
+    static [COMPONENT_MARKER]: boolean;
+    /** Zod schema for validating component props (excluding children) */
+    static schema: ZodObject<ZodRawShape>;
+    /** Optional Zod schema for validating the resolved value */
+    static resolveSchema?: ZodObject<ZodRawShape>;
+    /**
+     * When true, the name-hoisting Babel plugin will hoist this component's
+     * `name` prop to a variable declaration. Components that use `name` for
+     * variable creation (e.g., File, ReviewFile) should set this to true.
+     * Components that use `name` for identification (e.g., Section, Role)
+     * leave this unset.
+     */
+    static hoistName?: boolean;
+    /**
+     * Optional: Compute the resolved value for this component.
+     *
+     * If implemented, this method is called before render().
+     * The resolved value is stored and can be passed to other components.
+     *
+     * @param props - The properties passed to the component
+     * @param context - The render context containing environment and inputs
+     * @returns The resolved value, or a Promise resolving to the value for async components
+     */
+    resolve?(props: Props, context: RenderContext): ResolveType | Promise<ResolveType>;
+    /**
+     * Get the LLM provider from the render context.
+     *
+     * @param context - The render context
+     * @returns The LLM provider string
+     */
+    protected getProvider(context: RenderContext): LlmProvider;
+    /**
+     * Get the appropriate delimiter based on the output format in the render context.
+     * Returns 'markdown' if the output format is markdown, otherwise 'xml'.
+     *
+     * @param context - The render context
+     * @returns The delimiter style to use
+     */
+    protected getDelimiter(context: RenderContext): 'xml' | 'markdown' | 'none';
+    /**
+     * Check if children has meaningful content.
+     * Returns false for undefined, null, empty arrays, and empty strings.
+     */
+    protected hasContent(children: PuptNode): boolean;
+    /**
+     * Optional: Render the component with the given props and resolved value.
+     *
+     * If the component has a resolve() method, the resolved value is passed as the
+     * second argument. For backward compatibility, components without resolve() will
+     * receive undefined as the resolved value.
+     *
+     * @param props - The properties passed to the component
+     * @param resolvedValue - The value returned by resolve(), or undefined if no resolve() method
+     * @param context - The render context containing environment and inputs
+     * @returns The rendered output as a PuptNode, or a Promise resolving to a PuptNode for async components
+     */
+    render?(props: Props, resolvedValue: ResolveType, context: RenderContext): PuptNode | Promise<PuptNode>;
+}
+
+/**
+ * Symbol used to mark Component classes for identification
+ */
+declare const COMPONENT_MARKER: unique symbol;
+
+/**
+ * ComponentType can be either a class component (extending Component)
+ * or a function component.
+ */
+declare type ComponentType<P = Record<string, unknown>> = (new () => Component<P>) | ((props: P & {
+    children?: PuptNode;
+}) => PuptNode);
+
+/**
+ * Environment context containing all configuration
+ */
+declare type EnvironmentContext = z.infer<typeof environmentContextSchema>;
+
+/**
+ * Schema for the full environment context
+ */
+declare const environmentContextSchema: z.ZodObject<{
+    llm: z.ZodDefault<z.ZodEffects<z.ZodObject<{
+        model: z.ZodDefault<z.ZodString>;
+        provider: z.ZodDefault<z.ZodEnum<["anthropic", "openai", "google", "meta", "mistral", "deepseek", "xai", "cohere", "unspecified"]>>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        model: string;
+        provider: "unspecified" | "anthropic" | "openai" | "google" | "meta" | "mistral" | "deepseek" | "xai" | "cohere";
+        maxTokens?: number | undefined;
+        temperature?: number | undefined;
+    }, {
+        model?: string | undefined;
+        provider?: "unspecified" | "anthropic" | "openai" | "google" | "meta" | "mistral" | "deepseek" | "xai" | "cohere" | undefined;
+        maxTokens?: number | undefined;
+        temperature?: number | undefined;
+    }>, {
+        model: string;
+        provider: "unspecified" | "anthropic" | "openai" | "google" | "meta" | "mistral" | "deepseek" | "xai" | "cohere";
+        maxTokens?: number | undefined;
+        temperature?: number | undefined;
+    }, {
+        model?: string | undefined;
+        provider?: "unspecified" | "anthropic" | "openai" | "google" | "meta" | "mistral" | "deepseek" | "xai" | "cohere" | undefined;
+        maxTokens?: number | undefined;
+        temperature?: number | undefined;
+    }>>;
+    output: z.ZodDefault<z.ZodObject<{
+        format: z.ZodDefault<z.ZodEnum<["xml", "markdown", "json", "text", "unspecified"]>>;
+        trim: z.ZodDefault<z.ZodBoolean>;
+        indent: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        format: "unspecified" | "xml" | "markdown" | "json" | "text";
+        trim: boolean;
+        indent: string;
+    }, {
+        format?: "unspecified" | "xml" | "markdown" | "json" | "text" | undefined;
+        trim?: boolean | undefined;
+        indent?: string | undefined;
+    }>>;
+    code: z.ZodDefault<z.ZodObject<{
+        language: z.ZodDefault<z.ZodString>;
+        highlight: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        language: string;
+        highlight?: boolean | undefined;
+    }, {
+        language?: string | undefined;
+        highlight?: boolean | undefined;
+    }>>;
+    user: z.ZodDefault<z.ZodObject<{
+        editor: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        editor: string;
+    }, {
+        editor?: string | undefined;
+    }>>;
+    runtime: z.ZodDefault<z.ZodObject<{
+        hostname: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+        cwd: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodString>;
+        os: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodOptional<z.ZodNumber>;
+        date: z.ZodOptional<z.ZodString>;
+        time: z.ZodOptional<z.ZodString>;
+        uuid: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        hostname: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+        cwd: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodString>;
+        os: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodOptional<z.ZodNumber>;
+        date: z.ZodOptional<z.ZodString>;
+        time: z.ZodOptional<z.ZodString>;
+        uuid: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        hostname: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+        cwd: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodString>;
+        os: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodOptional<z.ZodNumber>;
+        date: z.ZodOptional<z.ZodString>;
+        time: z.ZodOptional<z.ZodString>;
+        uuid: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    prompt: z.ZodDefault<z.ZodObject<{
+        includeRole: z.ZodDefault<z.ZodBoolean>;
+        includeFormat: z.ZodDefault<z.ZodBoolean>;
+        includeConstraints: z.ZodDefault<z.ZodBoolean>;
+        includeSuccessCriteria: z.ZodDefault<z.ZodBoolean>;
+        includeGuardrails: z.ZodDefault<z.ZodBoolean>;
+        defaultRole: z.ZodDefault<z.ZodString>;
+        defaultExpertise: z.ZodDefault<z.ZodString>;
+        delimiter: z.ZodDefault<z.ZodEnum<["xml", "markdown", "none"]>>;
+    }, "strip", z.ZodTypeAny, {
+        includeRole: boolean;
+        includeFormat: boolean;
+        includeConstraints: boolean;
+        includeSuccessCriteria: boolean;
+        includeGuardrails: boolean;
+        defaultRole: string;
+        defaultExpertise: string;
+        delimiter: "xml" | "markdown" | "none";
+    }, {
+        includeRole?: boolean | undefined;
+        includeFormat?: boolean | undefined;
+        includeConstraints?: boolean | undefined;
+        includeSuccessCriteria?: boolean | undefined;
+        includeGuardrails?: boolean | undefined;
+        defaultRole?: string | undefined;
+        defaultExpertise?: string | undefined;
+        delimiter?: "xml" | "markdown" | "none" | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    code: {
+        language: string;
+        highlight?: boolean | undefined;
+    };
+    llm: {
+        model: string;
+        provider: "unspecified" | "anthropic" | "openai" | "google" | "meta" | "mistral" | "deepseek" | "xai" | "cohere";
+        maxTokens?: number | undefined;
+        temperature?: number | undefined;
+    };
+    output: {
+        format: "unspecified" | "xml" | "markdown" | "json" | "text";
+        trim: boolean;
+        indent: string;
+    };
+    user: {
+        editor: string;
+    };
+    runtime: {
+        hostname?: string | undefined;
+        username?: string | undefined;
+        cwd?: string | undefined;
+        platform?: string | undefined;
+        os?: string | undefined;
+        locale?: string | undefined;
+        timestamp?: number | undefined;
+        date?: string | undefined;
+        time?: string | undefined;
+        uuid?: string | undefined;
+    } & {
+        [k: string]: unknown;
+    };
+    prompt: {
+        includeRole: boolean;
+        includeFormat: boolean;
+        includeConstraints: boolean;
+        includeSuccessCriteria: boolean;
+        includeGuardrails: boolean;
+        defaultRole: string;
+        defaultExpertise: string;
+        delimiter: "xml" | "markdown" | "none";
+    };
+}, {
+    code?: {
+        language?: string | undefined;
+        highlight?: boolean | undefined;
+    } | undefined;
+    llm?: {
+        model?: string | undefined;
+        provider?: "unspecified" | "anthropic" | "openai" | "google" | "meta" | "mistral" | "deepseek" | "xai" | "cohere" | undefined;
+        maxTokens?: number | undefined;
+        temperature?: number | undefined;
+    } | undefined;
+    output?: {
+        format?: "unspecified" | "xml" | "markdown" | "json" | "text" | undefined;
+        trim?: boolean | undefined;
+        indent?: string | undefined;
+    } | undefined;
+    user?: {
+        editor?: string | undefined;
+    } | undefined;
+    runtime?: z.objectInputType<{
+        hostname: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+        cwd: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodString>;
+        os: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodOptional<z.ZodNumber>;
+        date: z.ZodOptional<z.ZodString>;
+        time: z.ZodOptional<z.ZodString>;
+        uuid: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    prompt?: {
+        includeRole?: boolean | undefined;
+        includeFormat?: boolean | undefined;
+        includeConstraints?: boolean | undefined;
+        includeSuccessCriteria?: boolean | undefined;
+        includeGuardrails?: boolean | undefined;
+        defaultRole?: string | undefined;
+        defaultExpertise?: string | undefined;
+        delimiter?: "xml" | "markdown" | "none" | undefined;
+    } | undefined;
+}>;
+
+/**
+ * Fragment symbol for grouping elements without a wrapper
+ */
+export declare const Fragment: unique symbol;
+
+/**
+ * Create a JSX element with a single child.
+ * Called by the JSX transform for elements with one child.
+ *
+ * @param type - Element type (string tag, symbol like Fragment, or component)
+ * @param props - Properties including children
+ * @returns A PuptElement
+ */
+export declare function jsx<P extends Record<string, unknown>>(type: string | symbol | ComponentType<P>, props: P & {
+    children?: PuptNode;
+}): PuptElement<P>;
+
+/**
+ * Create a JSX element with multiple children.
+ * Called by the JSX transform for elements with multiple children.
+ * Implementation is the same as jsx since we normalize children either way.
+ *
+ * @param type - Element type (string tag, symbol like Fragment, or component)
+ * @param props - Properties including children array
+ * @returns A PuptElement
+ */
+export declare function jsxs<P extends Record<string, unknown>>(type: string | symbol | ComponentType<P>, props: P & {
+    children?: PuptNode;
+}): PuptElement<P>;
+
+/**
+ * Known LLM providers (model creators, not hosting platforms).
+ * Hosting platforms like AWS Bedrock and Azure are not included here
+ * because the provider represents who created the model, which determines
+ * the prompt optimization strategy.
+ */
+declare const LLM_PROVIDERS: readonly ["anthropic", "openai", "google", "meta", "mistral", "deepseek", "xai", "cohere", "unspecified"];
+
+declare type LlmProvider = typeof LLM_PROVIDERS[number];
+
+/**
+ * Action to open a URL in a browser
+ */
+declare interface OpenUrlAction {
+    type: 'openUrl';
+    url: string;
+    browser?: string;
+}
+
+/**
+ * Actions to be executed after the LLM response
+ */
+declare type PostExecutionAction = ReviewFileAction | OpenUrlAction | RunCommandAction;
+
+/** Symbol for element props */
+declare const PROPS: unique symbol;
+
+/**
+ * PuptElement represents a JSX element in the pupt-lib tree.
+ * Uses symbols for internal properties to prevent collision with property access.
+ */
+declare interface PuptElement<P = Record<string, unknown>> {
+    [TYPE]: string | symbol | ComponentType<P>;
+    [PROPS]: P;
+    [CHILDREN]: PuptNode[];
+}
+
+/**
+ * PuptNode represents any valid child of a JSX element.
+ * Can be primitives, elements, or arrays of nodes.
+ */
+declare type PuptNode = string | number | boolean | null | undefined | PuptElement | PuptNode[];
+
+/**
+ * Render context passed to components during rendering
+ */
+declare interface RenderContext {
+    inputs: Map<string, unknown>;
+    env: EnvironmentContext;
+    postExecution: PostExecutionAction[];
+    errors: RenderError[];
+    metadata: Map<string, unknown>;
+}
+
+/**
+ * A validation or runtime error encountered during rendering
+ */
+declare interface RenderError {
+    /** Component class name or registry name, e.g. "Section" */
+    component: string;
+    /** The specific prop that failed validation, or null for cross-field/runtime errors */
+    prop: string | null;
+    /** Human-readable error message */
+    message: string;
+    /** Error code (Zod issue code or 'runtime_error' / 'missing_schema') */
+    code: string;
+    /** Path within the props object */
+    path: (string | number)[];
+    /** The value that was received */
+    received?: unknown;
+    /** The expected type or constraint */
+    expected?: string;
+}
+
+/**
+ * Action to open a file for review in an editor
+ */
+declare interface ReviewFileAction {
+    type: 'reviewFile';
+    file: string;
+    editor?: string;
+}
+
+/**
+ * Action to execute a shell command
+ */
+declare interface RunCommandAction {
+    type: 'runCommand';
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+}
+
+/** Symbol for element type */
+declare const TYPE: unique symbol;
+
+export { }