@bluefly/openstandardagents 0.2.9 → 0.3.0

package/dist/types/workflow.d.ts

@@ -0,0 +1,283 @@
+/**
+ * OSSA Workflow Types
+ * Type definitions for kind: Workflow - composition of Tasks and Agents
+ */
+import { JSONSchemaDefinition } from './task';
+/**
+ * Trigger types
+ */
+export type TriggerType = 'webhook' | 'cron' | 'event' | 'manual';
+/**
+ * Workflow step kinds
+ */
+export type WorkflowStepKind = 'Task' | 'Agent' | 'Parallel' | 'Conditional' | 'Loop';
+/**
+ * Failure handling actions
+ */
+export type FailureAction = 'halt' | 'continue' | 'rollback' | 'notify' | 'compensate';
+/**
+ * Step error actions
+ */
+export type StepErrorAction = 'fail' | 'continue' | 'goto' | 'compensate';
+/**
+ * Notification channels
+ */
+export type NotificationChannel = 'email' | 'slack' | 'webhook' | 'pagerduty';
+/**
+ * Workflow trigger configuration
+ */
+export interface WorkflowTrigger {
+    /** Trigger type */
+    type: TriggerType;
+    /** Webhook path (for type=webhook) */
+    path?: string;
+    /** Cron expression (for type=cron) */
+    schedule?: string;
+    /** Event source (for type=event) */
+    source?: string;
+    /** Event name (for type=event) */
+    event?: string;
+    /** Event filter conditions */
+    filter?: Record<string, unknown>;
+}
+/**
+ * Secret reference
+ */
+export interface SecretRef {
+    /** Secret name available to steps */
+    name: string;
+    /** Secret reference (e.g., vault://secret/api-key) */
+    ref: string;
+}
+/**
+ * Workflow context configuration
+ */
+export interface WorkflowContext {
+    /** Workflow-level variables */
+    variables?: Record<string, unknown>;
+    /** Secret references available to steps */
+    secrets?: SecretRef[];
+}
+/**
+ * Concurrency control
+ */
+export interface WorkflowConcurrency {
+    /** Concurrency group name */
+    group?: string;
+    /** Cancel running workflow if new one starts in same group */
+    cancel_in_progress?: boolean;
+}
+/**
+ * Retry policy
+ */
+export interface RetryPolicy {
+    /** Maximum retry attempts */
+    max_attempts?: number;
+    /** Backoff strategy */
+    backoff?: 'fixed' | 'exponential' | 'linear';
+    /** Initial delay in milliseconds */
+    initial_delay_ms?: number;
+    /** Maximum delay in milliseconds */
+    max_delay_ms?: number;
+}
+/**
+ * Failure notification configuration
+ */
+export interface FailureNotification {
+    /** Notification channels */
+    channels?: NotificationChannel[];
+    /** Notification template reference */
+    template?: string;
+}
+/**
+ * Workflow error handling configuration
+ */
+export interface WorkflowErrorHandling {
+    /** Action on step failure */
+    on_failure?: FailureAction;
+    /** Steps to run on rollback/compensate */
+    compensation_steps?: WorkflowStep[];
+    /** Notification on failure */
+    notification?: FailureNotification;
+    /** Retry policy */
+    retry_policy?: RetryPolicy;
+}
+/**
+ * Workflow observability configuration
+ */
+export interface WorkflowObservability {
+    /** Tracing configuration */
+    tracing?: {
+        enabled?: boolean;
+        propagate_context?: boolean;
+    };
+    /** Metrics configuration */
+    metrics?: {
+        enabled?: boolean;
+        custom_labels?: Record<string, string>;
+    };
+    /** Logging configuration */
+    logging?: {
+        level?: 'debug' | 'info' | 'warn' | 'error';
+    };
+}
+/**
+ * Step output mapping
+ */
+export interface StepOutputMapping {
+    /** Variable name to store output */
+    to?: string;
+    /** Specific fields to extract from output */
+    fields?: string[];
+}
+/**
+ * Step retry configuration
+ */
+export interface StepRetry {
+    /** Maximum retry attempts */
+    max_attempts?: number;
+    /** Backoff strategy */
+    backoff_strategy?: 'fixed' | 'exponential' | 'linear';
+    /** Initial delay in milliseconds */
+    initial_delay_ms?: number;
+    /** Error codes that should trigger retry */
+    retryable_errors?: string[];
+}
+/**
+ * Step error handling
+ */
+export interface StepErrorHandling {
+    /** Action on error */
+    action?: StepErrorAction;
+    /** Step ID to jump to on error (for action: goto) */
+    goto?: string;
+    /** Compensation step to run on error */
+    compensation?: WorkflowStep;
+}
+/**
+ * Loop configuration
+ */
+export interface LoopConfig {
+    /** Expression returning array to iterate over */
+    over: string;
+    /** Variable name for current item */
+    as?: string;
+    /** Variable name for current index */
+    index?: string;
+    /** Maximum parallel iterations */
+    parallelism?: number;
+}
+/**
+ * Conditional branch
+ */
+export interface ConditionalBranch {
+    /** Branch condition expression */
+    condition: string;
+    /** Steps to run if condition matches */
+    steps: WorkflowStep[];
+}
+/**
+ * Workflow step
+ */
+export interface WorkflowStep {
+    /** Step identifier (unique within workflow) */
+    id: string;
+    /** Human-readable step name */
+    name?: string;
+    /** Step type */
+    kind?: WorkflowStepKind;
+    /** Reference to Task or Agent manifest file */
+    ref?: string;
+    /** Inline Task or Agent specification */
+    inline?: Record<string, unknown>;
+    /** Input mapping using expression syntax */
+    input?: Record<string, unknown>;
+    /** Output mapping to workflow context */
+    output?: StepOutputMapping;
+    /** Condition expression for conditional execution */
+    condition?: string;
+    /** Explicit dependencies on other steps */
+    depends_on?: string[];
+    /** Steps to run in parallel (for kind: Parallel) */
+    parallel?: WorkflowStep[];
+    /** Conditional branches (for kind: Conditional) */
+    branches?: ConditionalBranch[];
+    /** Steps to run if no branch condition matches */
+    else?: WorkflowStep[];
+    /** Loop configuration (for kind: Loop) */
+    loop?: LoopConfig;
+    /** Nested steps (for Loop and Conditional kinds) */
+    steps?: WorkflowStep[];
+    /** Step-specific retry configuration */
+    retry?: StepRetry;
+    /** Step-specific timeout in seconds */
+    timeout_seconds?: number;
+    /** Continue workflow even if this step fails */
+    continue_on_error?: boolean;
+    /** Step-specific error handling */
+    on_error?: StepErrorHandling;
+    /** Step labels for filtering */
+    labels?: Record<string, string>;
+}
+/**
+ * WorkflowSpec - Specification for workflow composition (kind: Workflow)
+ */
+export interface WorkflowSpec {
+    /** Triggers that start the workflow */
+    triggers?: WorkflowTrigger[];
+    /** JSON Schema for workflow input validation */
+    inputs?: JSONSchemaDefinition;
+    /** JSON Schema for workflow output validation */
+    outputs?: JSONSchemaDefinition;
+    /** Workflow steps */
+    steps: WorkflowStep[];
+    /** Shared context available to all steps */
+    context?: WorkflowContext;
+    /** Concurrency control */
+    concurrency?: WorkflowConcurrency;
+    /** Workflow-level error handling */
+    error_handling?: WorkflowErrorHandling;
+    /** Maximum workflow execution time in seconds */
+    timeout_seconds?: number;
+    /** Workflow observability configuration */
+    observability?: WorkflowObservability;
+}
+/**
+ * OSSA Workflow manifest (kind: Workflow)
+ */
+export interface OssaWorkflow {
+    /** OSSA API version */
+    apiVersion: string;
+    /** Resource type - must be 'Workflow' */
+    kind: 'Workflow';
+    /** Workflow metadata */
+    metadata: {
+        name: string;
+        version?: string;
+        description?: string;
+        labels?: Record<string, string>;
+        annotations?: Record<string, string>;
+    };
+    /** Workflow specification */
+    spec: WorkflowSpec;
+    /** Framework-specific extensions */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Type guard to check if manifest is a Workflow
+ */
+export declare function isOssaWorkflow(manifest: unknown): manifest is OssaWorkflow;
+/**
+ * Create an empty Workflow manifest with defaults
+ */
+export declare function createWorkflowManifest(name: string, options?: Partial<OssaWorkflow>): OssaWorkflow;
+/**
+ * Helper to create a workflow step
+ */
+export declare function createStep(id: string, kind: WorkflowStepKind, options?: Partial<WorkflowStep>): WorkflowStep;
+/**
+ * Helper to create an expression reference
+ * @example expr('steps.fetch.output.content') => '${{ steps.fetch.output.content }}'
+ */
+export declare function expr(path: string): string;
+//# sourceMappingURL=workflow.d.ts.map

package/dist/types/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../src/types/workflow.ts"],"names":[],"mappings":"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"}

package/dist/types/workflow.js

@@ -0,0 +1,51 @@
+/**
+ * OSSA Workflow Types
+ * Type definitions for kind: Workflow - composition of Tasks and Agents
+ */
+import { getApiVersion } from '../utils/version.js';
+/**
+ * Type guard to check if manifest is a Workflow
+ */
+export function isOssaWorkflow(manifest) {
+    return (typeof manifest === 'object' &&
+        manifest !== null &&
+        'kind' in manifest &&
+        manifest.kind === 'Workflow');
+}
+/**
+ * Create an empty Workflow manifest with defaults
+ */
+export function createWorkflowManifest(name, options) {
+    return {
+        apiVersion: getApiVersion(),
+        kind: 'Workflow',
+        metadata: {
+            name,
+            version: '1.0.0',
+            ...options?.metadata,
+        },
+        spec: {
+            steps: [],
+            ...options?.spec,
+        },
+        extensions: options?.extensions,
+    };
+}
+/**
+ * Helper to create a workflow step
+ */
+export function createStep(id, kind, options) {
+    return {
+        id,
+        kind,
+        ...options,
+    };
+}
+/**
+ * Helper to create an expression reference
+ * @example expr('steps.fetch.output.content') => '${{ steps.fetch.output.content }}'
+ */
+export function expr(path) {
+    return `\${{ ${path} }}`;
+}
+//# sourceMappingURL=workflow.js.map

package/dist/types/workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../../src/types/workflow.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AA2RpD;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,QAAiB;IAC9C,OAAO,CACL,OAAO,QAAQ,KAAK,QAAQ;QAC5B,QAAQ,KAAK,IAAI;QACjB,MAAM,IAAI,QAAQ;QACjB,QAAoC,CAAC,IAAI,KAAK,UAAU,CAC1D,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAY,EACZ,OAA+B;IAE/B,OAAO;QACL,UAAU,EAAE,aAAa,EAAE;QAC3B,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE;YACR,IAAI;YACJ,OAAO,EAAE,OAAO;YAChB,GAAG,OAAO,EAAE,QAAQ;SACrB;QACD,IAAI,EAAE;YACJ,KAAK,EAAE,EAAE;YACT,GAAG,OAAO,EAAE,IAAI;SACjB;QACD,UAAU,EAAE,OAAO,EAAE,UAAU;KAChC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CACxB,EAAU,EACV,IAAsB,EACtB,OAA+B;IAE/B,OAAO;QACL,EAAE;QACF,IAAI;QACJ,GAAG,OAAO;KACX,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,IAAY;IAC/B,OAAO,QAAQ,IAAI,KAAK,CAAC;AAC3B,CAAC"}

package/dist/utils/path-validator.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Path Validation Utility
+ * Prevents path traversal attacks and validates file access
+ */
+export declare class PathValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates a file path for security and existence
+ * @param filePath - The file path to validate
+ * @param basePath - Optional base path to restrict access (defaults to null for no restriction)
+ * @returns Absolute, validated file path
+ * @throws PathValidationError if path is invalid or inaccessible
+ */
+export declare function validateFilePath(filePath: string, basePath?: string | null): string;
+/**
+ * Validates a directory path for security and existence
+ * @param dirPath - The directory path to validate
+ * @param basePath - Optional base path to restrict access (defaults to null for no restriction)
+ * @returns Absolute, validated directory path
+ * @throws PathValidationError if path is invalid or inaccessible
+ */
+export declare function validateDirectoryPath(dirPath: string, basePath?: string | null): string;
+//# sourceMappingURL=path-validator.d.ts.map

package/dist/utils/path-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-validator.d.ts","sourceRoot":"","sources":["../../src/utils/path-validator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,GAAG,IAAW,GAAG,MAAM,CA2BzF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,GAAG,IAAW,GAAG,MAAM,CA0B7F"}

package/dist/utils/path-validator.js

@@ -0,0 +1,70 @@
+/**
+ * Path Validation Utility
+ * Prevents path traversal attacks and validates file access
+ */
+import { resolve, normalize } from 'path';
+import { existsSync, statSync } from 'fs';
+export class PathValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PathValidationError';
+    }
+}
+/**
+ * Validates a file path for security and existence
+ * @param filePath - The file path to validate
+ * @param basePath - Optional base path to restrict access (defaults to null for no restriction)
+ * @returns Absolute, validated file path
+ * @throws PathValidationError if path is invalid or inaccessible
+ */
+export function validateFilePath(filePath, basePath = null) {
+    // Normalize and resolve path
+    const normalized = normalize(filePath);
+    const resolved = resolve(normalized);
+    // If basePath is provided, enforce path traversal protection
+    if (basePath !== null) {
+        const baseResolved = resolve(basePath);
+        if (!resolved.startsWith(baseResolved)) {
+            throw new PathValidationError(`Access denied: Path '${filePath}' attempts to escape base directory`);
+        }
+    }
+    // Check if path exists
+    if (!existsSync(resolved)) {
+        throw new PathValidationError(`File not found: ${filePath}`);
+    }
+    // Ensure it's a file, not a directory
+    const stats = statSync(resolved);
+    if (!stats.isFile()) {
+        throw new PathValidationError(`Path is not a file: ${filePath}`);
+    }
+    return resolved;
+}
+/**
+ * Validates a directory path for security and existence
+ * @param dirPath - The directory path to validate
+ * @param basePath - Optional base path to restrict access (defaults to null for no restriction)
+ * @returns Absolute, validated directory path
+ * @throws PathValidationError if path is invalid or inaccessible
+ */
+export function validateDirectoryPath(dirPath, basePath = null) {
+    const normalized = normalize(dirPath);
+    const resolved = resolve(normalized);
+    // If basePath is provided, enforce path traversal protection
+    if (basePath !== null) {
+        const baseResolved = resolve(basePath);
+        if (!resolved.startsWith(baseResolved)) {
+            throw new PathValidationError(`Access denied: Path '${dirPath}' attempts to escape base directory`);
+        }
+    }
+    // Check if path exists
+    if (!existsSync(resolved)) {
+        throw new PathValidationError(`Directory not found: ${dirPath}`);
+    }
+    // Ensure it's a directory
+    const stats = statSync(resolved);
+    if (!stats.isDirectory()) {
+        throw new PathValidationError(`Path is not a directory: ${dirPath}`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=path-validator.js.map

package/dist/utils/path-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-validator.js","sourceRoot":"","sources":["../../src/utils/path-validator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;AAE1C,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,WAA0B,IAAI;IAC/E,6BAA6B;IAC7B,MAAM,UAAU,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAErC,6DAA6D;IAC7D,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QACvC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,mBAAmB,CAC3B,wBAAwB,QAAQ,qCAAqC,CACtE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,uBAAuB;IACvB,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,mBAAmB,CAAC,mBAAmB,QAAQ,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,sCAAsC;IACtC,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACjC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QACpB,MAAM,IAAI,mBAAmB,CAAC,uBAAuB,QAAQ,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe,EAAE,WAA0B,IAAI;IACnF,MAAM,UAAU,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAErC,6DAA6D;IAC7D,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QACvC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,mBAAmB,CAC3B,wBAAwB,OAAO,qCAAqC,CACrE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,uBAAuB;IACvB,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,mBAAmB,CAAC,wBAAwB,OAAO,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,0BAA0B;IAC1B,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACjC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;QACzB,MAAM,IAAI,mBAAmB,CAAC,4BAA4B,OAAO,EAAE,CAAC,CAAC;IACvE,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/utils/version.d.ts

@@ -2,22 +2,26 @@
  * OSSA Version Utilities
  *
  * Provides dynamic version detection from package.json
- * NEVER hardcode version strings - use these utilities
+ *
+ * CRITICAL: NO HARDCODED VERSION STRINGS ANYWHERE
+ * All versions MUST be derived from package.json or environment variables.
+ *
+ * NOTE: This module is designed to work with both ESM and CommonJS (Jest).
  */
 export interface VersionInfo {
-    /** Full version string (e.g., "0.2.8") */
+    /** Full version string (e.g., "0.3.0") - dynamically derived */
     version: string;
-    /** Major version (e.g., 0) */
+    /** Major version */
     major: number;
-    /** Minor version (e.g., 2) */
+    /** Minor version */
     minor: number;
-    /** Patch version (e.g., 8) */
+    /** Patch version */
     patch: number;
     /** Prerelease tag if any (e.g., "RC", "beta") */
     prerelease?: string;
-    /** Schema directory name (e.g., "v0.2.8") */
+    /** Schema directory name (e.g., "v0.3.0") */
     schemaDir: string;
-    /** Schema filename (e.g., "ossa-0.2.8.schema.json") */
+    /** Schema filename (e.g., "ossa-0.3.0.schema.json") */
     schemaFile: string;
     /** Full schema path relative to project root */
     schemaPath: string;
@@ -29,6 +33,7 @@ export interface VersionInfo {
  *
  * @param forceRefresh - If true, bypasses cache and re-reads package.json
  * @returns VersionInfo object with all version details
+ * @throws Error if version cannot be determined dynamically
  *
  * @example
  * const { version, schemaPath, apiVersion } = getVersionInfo();
@@ -49,7 +54,7 @@ export declare function getSchemaPath(): string;
  */
 export declare function getApiVersion(): string;
 /**
- * Get the schema directory (e.g., "v0.2.8")
+ * Get the schema directory (e.g., "v0.3.0")
  */
 export declare function getSchemaDir(): string;
 /**
@@ -65,4 +70,8 @@ export declare function getSupportedVersions(): string[];
  * Resolve absolute path to schema file
  */
 export declare function resolveSchemaPath(projectRoot?: string): string;
+/**
+ * Clear the cached version info (useful for testing)
+ */
+export declare function clearVersionCache(): void;
 //# sourceMappingURL=version.d.ts.map

package/dist/utils/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,MAAM,WAAW,WAAW;IAC1B,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAoCD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,YAAY,UAAQ,GAAG,WAAW,CAiDhE;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,EAAE,CAc/C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAG9D"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAmHD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,YAAY,UAAQ,GAAG,WAAW,CAoBhE;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,EAAE,CAc/C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}