@codemieai/cdk 0.1.270

package/dist/index.d.ts

@@ -0,0 +1,584 @@
+import { z } from 'zod';
+import { Integration, BaseDataSourceCreateParams, BaseCodeParams, DataSourceType, BaseConfluenceParams, BaseJiraParams, BaseGoogleParams, BaseFileParams, AssistantCreateParams, ToolKitDetails, ToolDetails, MCPServerDetails, WorkflowCreateParams, CodeMieClient } from 'codemie-sdk';
+
+declare const appConfigSchema: z.ZodObject<{
+    rootDir: z.ZodString;
+    codemieConfig: z.ZodString;
+    codemieState: z.ZodString;
+    backupsDirectory: z.ZodString;
+}, z.core.$strip>;
+type AppConfig = z.infer<typeof appConfigSchema>;
+
+interface CodemieConfig {
+    version: string;
+    project: {
+        name: string;
+        description: string;
+    };
+    environment: {
+        codemie_api_url: string;
+        auth_server_url: string;
+        auth_realm_name: string;
+        client_id?: string;
+        client_secret?: string;
+        username?: string;
+        password?: string;
+    };
+    imported: {
+        assistants: ImportedResource[];
+        datasources: ImportedResource[];
+        integrations: IntegrationDefinition[];
+    };
+    tool_definitions?: {
+        [alias: string]: ToolDefinition;
+    };
+    datasource_defaults?: {
+        [type: string]: Partial<DatasourceResource>;
+    };
+    resources: {
+        assistants?: AssistantResource[];
+        datasources?: DatasourceResource[];
+        workflows?: WorkflowResource[];
+    };
+}
+type IntegrationDefinition = Integration;
+/**
+ * Reference to a named integration in IaC config
+ */
+interface IntegrationRef {
+    $ref: string;
+}
+/**
+ * Integration reference for IaC configurations
+ * Can be:
+ * - { $ref: string } - Reference to named integration
+ * - Integration - Full integration object from SDK
+ * - null
+ */
+type IntegrationReference = IntegrationRef | Integration | null;
+/**
+ * IaC representation of a tool (extends SDK ToolDetails)
+ * Override: settings can be $ref, settings_config optional
+ */
+interface IaCTool extends Omit<ToolDetails, 'settings' | 'settings_config'> {
+    settings_config?: boolean;
+    settings?: IntegrationReference;
+}
+/**
+ * IaC representation of a toolkit (extends SDK ToolKitDetails)
+ * Override: settings can be $ref, tools use IaCTool, some fields optional
+ */
+interface IaCToolkit extends Omit<ToolKitDetails, 'settings' | 'tools' | 'settings_config' | 'is_external'> {
+    settings_config?: boolean;
+    is_external?: boolean;
+    tools: IaCTool[];
+    settings?: IntegrationReference;
+}
+/**
+ * IaC representation of MCP server (extends SDK MCPServerDetails)
+ * Override: settings/mcp_connect_auth_token can be $ref, enabled optional
+ */
+interface IaCMcpServer extends Omit<MCPServerDetails, 'settings' | 'mcp_connect_auth_token' | 'enabled'> {
+    enabled?: boolean;
+    settings?: IntegrationReference;
+    mcp_connect_auth_token?: IntegrationReference;
+}
+interface ToolDefinition {
+    $ref: string;
+    name: string;
+    label?: string;
+    settings_config?: boolean;
+    user_description?: string;
+    settings?: IntegrationReference;
+    [key: string]: unknown;
+}
+interface ImportedResource {
+    name: string;
+    id: string;
+    type?: string;
+}
+/**
+ * Assistant resource configuration (IaC layer)
+ * Combines IaC-specific fields with all SDK AssistantCreateParams fields
+ * Automatically inherits all new fields from SDK
+ */
+interface AssistantResource extends Partial<Omit<AssistantCreateParams, 'project' | 'system_prompt' | 'llm_model_type' | 'toolkits' | 'mcp_servers'>> {
+    name: string;
+    description: string;
+    prompt: string;
+    model: string;
+    toolkits?: IaCToolkit[];
+    mcp_servers?: IaCMcpServer[];
+    config?: string;
+    sub_assistants?: string[];
+    datasource_names?: string[];
+    categories?: string[];
+}
+/**
+ * Base datasource configuration (IaC-specific fields only)
+ */
+interface BaseIaCDatasourceConfig {
+    name: string;
+    description: string;
+    $ref?: string;
+    force_reindex?: boolean;
+}
+/**
+ * Base configuration for all datasource types (IaC + SDK fields)
+ * Extends SDK BaseDataSourceCreateParams + adds IaC-specific fields
+ */
+interface BaseDatasourceConfig extends BaseIaCDatasourceConfig, Partial<Omit<BaseDataSourceCreateParams, 'project_name' | 'name' | 'description'>> {
+}
+/**
+ * Code datasource configuration (GitHub/GitLab/Bitbucket repositories)
+ * Automatically inherits all new fields from SDK BaseCodeParams
+ */
+interface CodeDatasourceResource extends BaseDatasourceConfig, Partial<BaseCodeParams> {
+    type: typeof DataSourceType.CODE;
+}
+/**
+ * Confluence datasource configuration
+ * Automatically inherits all new fields from SDK BaseConfluenceParams
+ */
+interface ConfluenceDatasourceResource extends BaseDatasourceConfig, Partial<BaseConfluenceParams> {
+    type: typeof DataSourceType.CONFLUENCE;
+}
+/**
+ * Jira datasource configuration
+ * Automatically inherits all new fields from SDK BaseJiraParams
+ */
+interface JiraDatasourceResource extends BaseDatasourceConfig, Partial<BaseJiraParams> {
+    type: typeof DataSourceType.JIRA;
+}
+/**
+ * Google Docs datasource configuration
+ * Automatically inherits all new fields from SDK BaseGoogleParams
+ */
+interface GoogleDatasourceResource extends BaseDatasourceConfig, Partial<BaseGoogleParams> {
+    type: typeof DataSourceType.GOOGLE;
+}
+/**
+ * File datasource configuration (uploaded files)
+ * Automatically inherits all new fields from SDK BaseFileParams
+ */
+interface FileDatasourceResource extends BaseDatasourceConfig, Partial<BaseFileParams> {
+    type: typeof DataSourceType.FILE;
+}
+/**
+ * Other/generic datasource configuration (for any other SDK datasource types)
+ */
+interface OtherDatasourceResource extends BaseDatasourceConfig {
+    type?: typeof DataSourceType.BEDROCK | typeof DataSourceType.CHUNK_SUMMARY | typeof DataSourceType.JSON | typeof DataSourceType.PROVIDER | typeof DataSourceType.SUMMARY;
+}
+/**
+ * Discriminated union of all datasource types
+ * Mirrors SDK DataSourceCreateParams structure
+ * New datasource types in SDK will be automatically supported
+ */
+type DatasourceResource = CodeDatasourceResource | ConfluenceDatasourceResource | JiraDatasourceResource | GoogleDatasourceResource | FileDatasourceResource | OtherDatasourceResource;
+/**
+ * Base Workflow configuration (IaC-specific fields only)
+ */
+interface BaseWorkflowConfig {
+    name: string;
+    description: string;
+    definition: string;
+}
+/**
+ * Workflow resource configuration (IaC layer)
+ * Combines IaC-specific fields with all SDK WorkflowCreateParams fields
+ * Automatically inherits all new fields from SDK
+ */
+interface WorkflowResource extends BaseWorkflowConfig, Partial<Omit<WorkflowCreateParams, 'project' | 'name' | 'description' | 'yaml_config'>> {
+}
+interface AssistantConfig {
+    includes?: string[];
+    placeholders?: Record<string, unknown>;
+    validation?: {
+        max_length?: number;
+        required_sections?: string[];
+    };
+    metadata?: Record<string, unknown>;
+}
+interface StateFile {
+    version: string;
+    project: string;
+    lastSync: string | null;
+    resources: {
+        assistants: Record<string, AssistantState>;
+        datasources: Record<string, DatasourceState>;
+        workflows: Record<string, WorkflowState>;
+    };
+}
+interface AssistantState {
+    id: string;
+    lastDeployed: string;
+    promptChecksum: string;
+    configChecksum: string;
+}
+interface DatasourceState {
+    id: string;
+    lastDeployed: string;
+    configChecksum: string;
+}
+interface WorkflowState {
+    id: string;
+    lastDeployed: string;
+    workflowYamlChecksum: string;
+    configChecksum: string;
+}
+interface WorkflowYaml {
+    assistants: WorkflowAssistantReference[];
+    states: WorkflowStateDefinition[];
+}
+interface WorkflowAssistantReference {
+    id: string;
+    assistant_id?: string;
+    assistant_name?: string;
+    model?: string;
+    name?: string;
+    system_prompt?: string;
+}
+interface WorkflowStateDefinition {
+    id: string;
+    assistant_id: string;
+    task: string;
+    output_schema: string;
+    next?: {
+        state_id: string;
+    };
+}
+interface Change {
+    type: 'create' | 'update' | 'no-change' | 'delete';
+    resourceType: 'assistant' | 'datasource' | 'workflow';
+    name: string;
+    details?: string;
+}
+
+declare class CodemieConfigLoader {
+    private readonly appConfig;
+    constructor(appConfig: AppConfig);
+    /**
+     * Load and parse the main codemie.yaml configuration file
+     */
+    loadConfig(): CodemieConfig;
+    /**
+     * Load assistant prompt file
+     */
+    loadPrompt(promptPath: string): string;
+    /**
+     * Load assistant configuration file
+     */
+    loadAssistantConfig(configPath: string): AssistantConfig;
+    /**
+     * Validate that all referenced files exist
+     */
+    validateFiles(config: CodemieConfig): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Resolve $import directives recursively
+     * Automatically handles:
+     * 1. Single resource import (object)
+     * 2. Multiple resources import (array)
+     * 3. Mixed inline + imports
+     * Includes circular import detection to prevent infinite recursion
+     */
+    private resolveImports;
+    /**
+     * Resolve imports in arrays
+     * Intelligently handles:
+     * - Inline objects (keep as-is)
+     * - $import with single object (add to array)
+     * - $import with array (flatten into parent array)
+     * Includes circular import detection
+     */
+    private resolveArrayImports;
+    /**
+     * Load YAML file with error handling
+     */
+    private loadYamlFile;
+    /**
+     * Recursively resolve all $ref in an object/array structure
+     * Handles both object references { $ref: "path" } and string references "$ref:path"
+     *
+     * @param current - Current node being processed (starts with root config, then recurses into children)
+     * @param rootConfig - Root config object (constant reference for resolving paths like "imported.integrations.xxx")
+     * @param path - Current path in config tree (for error messages, e.g., "resources.assistants[0].toolkits")
+     */
+    private resolveReferencesRecursive;
+    /**
+     * Resolve $ref items in arrays and flatten if they point to arrays
+     * Example: [{ $ref: "context_definitions.repos" }] where repos is [item1, item2]
+     * becomes [item1, item2]
+     */
+    private resolveArrayReferences;
+    /**
+     * Resolve object reference: { $ref: "path" }
+     * Replaces object with resolved data (in-place mutation)
+     */
+    private resolveObjectReference;
+    /**
+     * Resolve object properties recursively
+     * Handles both nested objects and "$ref:path" string references
+     */
+    private resolveObjectProperties;
+    /**
+     * Validate that datasource setting_id fields are strings (not objects)
+     * For datasources, setting_id must reference a string UUID, not an integration object
+     * Users should use .id suffix: $ref:imported.integrations.git_conn.id
+     */
+    private validateDatasourceIntegrationReferences;
+    /**
+     * Resolve a reference path like "imported.integrations.jira_main" or "tool_definitions.jira_tool"
+     * Supports nested paths like "imported.integrations.jira_main.id" to access specific fields
+     * Returns the referenced object or value from config
+     *
+     * Special handling for arrays:
+     * - imported.integrations (array): searches by 'alias' field
+     * - imported.assistants (array): searches by 'name' field
+     * - imported.datasources (array): searches by 'name' field
+     */
+    private resolveReference;
+    /**
+     * Apply datasource defaults based on $ref or type
+     * Priority: $ref (explicit) > type (fallback)
+     */
+    private applyDatasourceDefaults;
+    /**
+     * Type guard to check if value is a plain object (not array, not null)
+     */
+    private isPlainObject;
+    private isRefObject;
+    /**
+     * Substitute environment variables in configuration
+     * Supports syntax:
+     * - ${VAR_NAME} - required variable (throws if not set)
+     * - ${VAR_NAME:-default} - optional with default value (shell-style)
+     * - ${VAR_NAME:default} - optional with default value (simplified)
+     * - ${VAR_NAME:-} or ${VAR_NAME:} - optional with empty string default
+     */
+    private substituteEnvVars;
+}
+
+declare class StateManager {
+    private readonly statePath;
+    constructor(appConfig: AppConfig);
+    /**
+     * Load state file
+     */
+    loadState(): StateFile;
+    /**
+     * Save state file
+     */
+    saveState(state: StateFile): void;
+    /**
+     * Create empty state structure
+     */
+    private createEmptyState;
+    /**
+     * Update assistant state (keyed by NAME)
+     * @param name
+     * @param id
+     * @param promptContent
+     * @param assistantResource - The assistant resource object (used to calculate consistent checksum)
+     * @param buildConfig - Optional build-time configuration
+     */
+    updateAssistantState(name: string, id: string, promptContent: string, assistantResource: AssistantResource, buildConfig?: unknown): void;
+    /**
+     * Get assistant state by NAME
+     */
+    getAssistantState(name: string): AssistantState | undefined;
+    /**
+     * Delete assistant state by NAME
+     */
+    deleteAssistantState(name: string): void;
+    /**
+     * Update datasource state (keyed by NAME)
+     * @param datasourceResource - The datasource resource object (used to calculate consistent checksum)
+     */
+    updateDatasourceState(name: string, id: string, datasourceResource: DatasourceResource): void;
+    /**
+     * Get datasource state by NAME
+     */
+    getDatasourceState(name: string): DatasourceState | undefined;
+    /**
+     * Delete datasource state by NAME
+     */
+    deleteDatasourceState(name: string): void;
+    /**
+     * Update workflow state (keyed by NAME)
+     */
+    updateWorkflowState(name: string, id: string, workflowYamlChecksum: string, configChecksum: string): void;
+    /**
+     * Get workflow state by NAME
+     */
+    getWorkflowState(name: string): WorkflowState | undefined;
+    /**
+     * Delete workflow state by NAME
+     */
+    deleteWorkflowState(name: string): void;
+    /**
+     * Get all managed resources (for cleanup/destroy)
+     * Returns: { assistants: [name1, name2], datasources: [name1], workflows: [name1] }
+     */
+    getAllManagedResources(): {
+        assistants: string[];
+        datasources: string[];
+        workflows: string[];
+    };
+    /**
+     * Check if a resource is managed by IaC (exists in state.json)
+     * @param type Resource type ('assistant', 'datasource', 'workflow')
+     * @param name Resource name
+     */
+    isManagedResource(type: 'assistant' | 'datasource' | 'workflow', name: string): boolean;
+    /**
+     * Get ID by name for a specific resource type
+     */
+    getIdByName(type: 'assistant' | 'datasource' | 'workflow', name: string): string | undefined;
+}
+
+/**
+ * Creates and initializes a Codemie API client from config
+ *
+ * This factory function centralizes client creation to avoid code duplication
+ * across multiple scripts (apply, preview, destroy, validate).
+ *
+ * @param config - Codemie IaC configuration containing environment settings
+ * @returns Initialized CodeMieClient ready for API calls
+ */
+declare function createClient(config: CodemieConfig): Promise<CodeMieClient>;
+
+interface CleanupResult {
+    deleted: {
+        assistants: string[];
+        datasources: string[];
+        workflows: string[];
+    };
+    errors: Array<{
+        type: 'assistant' | 'datasource' | 'workflow';
+        name: string;
+        error: string;
+    }>;
+}
+declare class CleanupManager {
+    private client;
+    private stateManager;
+    constructor(client: CodeMieClient, stateManager: StateManager);
+    /**
+     * Check if an error indicates that a resource was not found on the platform
+     * Handles both proper 404 responses
+     */
+    private isNotFoundError;
+    /**
+     * Delete a resource with graceful handling for "not found" errors
+     * Returns true if deleted or not found, false if other error occurred
+     */
+    private deleteResourceSafely;
+    /**
+     * Find orphaned resources (in state but not in config)
+     * These are resources that were managed by IaC but removed from codemie.yaml
+     * Returns resource NAMES, not IDs
+     */
+    findOrphanedResources(config: CodemieConfig): {
+        assistants: string[];
+        datasources: string[];
+        workflows: string[];
+    };
+    /**
+     * Delete orphaned resources from platform
+     * SAFETY: Only deletes resources that are in state.json (managed by IaC)
+     * @param orphaned Object with resource NAMES (not IDs)
+     */
+    deleteOrphanedResources(orphaned: {
+        assistants: string[];
+        datasources: string[];
+        workflows: string[];
+    }): Promise<CleanupResult>;
+    /**
+     * Get summary of orphaned resources
+     */
+    getOrphanedSummary(orphaned: {
+        assistants: string[];
+        datasources: string[];
+        workflows: string[];
+    }): string;
+}
+
+declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    SILENT = 4
+}
+declare class Logger {
+    private static instance;
+    private level;
+    private constructor();
+    static getInstance(): Logger;
+    setLevel(level: LogLevel): void;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+declare const logger: Logger;
+
+interface DeploymentStats {
+    created: number;
+    updated: number;
+    unchanged: number;
+    failed: number;
+}
+/**
+ * Deploy all assistants from configuration
+ * Extracted from main() for better maintainability
+ */
+declare function deployAssistants(config: ReturnType<CodemieConfigLoader['loadConfig']>, client: Awaited<ReturnType<typeof createClient>>, loader: CodemieConfigLoader, stateManager: StateManager): Promise<DeploymentStats>;
+/**
+ * Deploy all datasources from configuration
+ * Extracted from main() for better maintainability
+ */
+declare function deployDatasources(config: ReturnType<CodemieConfigLoader['loadConfig']>, client: Awaited<ReturnType<typeof createClient>>, stateManager: StateManager): Promise<DeploymentStats>;
+/**
+ * Deploy all workflows from configuration
+ * Extracted from main() for better maintainability
+ */
+declare function deployWorkflows(config: ReturnType<CodemieConfigLoader['loadConfig']>, client: Awaited<ReturnType<typeof createClient>>, stateManager: StateManager, rootDir?: string): Promise<DeploymentStats>;
+declare function deployResources(options: {
+    appConfig: AppConfig;
+    prune?: boolean;
+}): Promise<void>;
+
+declare function validateConfig(options: {
+    appConfig: AppConfig;
+    checkApi?: boolean;
+}): Promise<{
+    success: boolean;
+    errors: string[];
+}>;
+
+declare function previewChanges(appConfig: AppConfig, existingClient?: CodeMieClient): Promise<{
+    changes: Change[];
+    summary: {
+        deleted: number;
+        created: number;
+        updated: number;
+        unchanged: number;
+        total: number;
+    };
+}>;
+
+declare function backupResources(options: {
+    appConfig: AppConfig;
+}): Promise<void>;
+
+declare function destroyResources(options: {
+    appConfig: AppConfig;
+    force?: boolean;
+}): Promise<void>;
+
+export { type AssistantConfig, type AssistantResource, type AssistantState, type Change, CleanupManager, type CodeDatasourceResource, type CodemieConfig, CodemieConfigLoader, type ConfluenceDatasourceResource, type DatasourceResource, type DatasourceState, type FileDatasourceResource, type GoogleDatasourceResource, type IaCMcpServer, type IaCTool, type IaCToolkit, type ImportedResource, type IntegrationDefinition, type IntegrationRef, type IntegrationReference, type JiraDatasourceResource, LogLevel, type OtherDatasourceResource, type StateFile, StateManager, type ToolDefinition, type WorkflowAssistantReference, type WorkflowResource, type WorkflowState, type WorkflowStateDefinition, type WorkflowYaml, backupResources, createClient, deployAssistants, deployDatasources, deployResources, deployWorkflows, destroyResources, logger, previewChanges, validateConfig };