digital-workers 2.0.2 → 2.1.1

package/src/is.js

@@ -0,0 +1,317 @@
+/**
+ * Type validation and checking functionality for digital workers
+ */
+import { generateObject } from 'ai-functions';
+import { schema as convertSchema } from 'ai-functions';
+/**
+ * Check if a value matches an expected type or schema
+ *
+ * Uses AI-powered validation for complex types and schemas.
+ * Can also perform type coercion when enabled.
+ *
+ * @param value - The value to check
+ * @param type - Type name or schema to validate against
+ * @param options - Validation options
+ * @returns Promise resolving to validation result
+ *
+ * @example
+ * ```ts
+ * // Simple type checking
+ * const result = await is('hello@example.com', 'email')
+ * console.log(result.valid) // true
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Schema validation
+ * const result = await is(
+ *   { name: 'John', age: 30 },
+ *   {
+ *     name: 'Full name',
+ *     age: 'Age in years (number)',
+ *     email: 'Email address',
+ *   }
+ * )
+ * console.log(result.valid) // false - missing email
+ * console.log(result.errors) // ['Missing required field: email']
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With coercion
+ * const result = await is('123', 'number', { coerce: true })
+ * console.log(result.valid) // true
+ * console.log(result.value) // 123 (as number)
+ * ```
+ */
+export async function is(value, type, options = {}) {
+    const { coerce = false, strict = false } = options;
+    // Handle simple type strings
+    if (typeof type === 'string') {
+        return validateSimpleType(value, type, { coerce, strict });
+    }
+    // Handle schema validation
+    return validateSchema(value, type, { coerce, strict });
+}
+/**
+ * Validate against a simple type name
+ */
+async function validateSimpleType(value, type, options) {
+    const { coerce, strict } = options;
+    // Built-in JavaScript types
+    const builtInTypes = {
+        string: (v) => typeof v === 'string',
+        number: (v) => typeof v === 'number' && !isNaN(v),
+        boolean: (v) => typeof v === 'boolean',
+        object: (v) => typeof v === 'object' && v !== null && !Array.isArray(v),
+        array: (v) => Array.isArray(v),
+        null: (v) => v === null,
+        undefined: (v) => v === undefined,
+        function: (v) => typeof v === 'function',
+    };
+    // Check built-in types first
+    if (type in builtInTypes) {
+        const isValid = builtInTypes[type](value);
+        if (!isValid && coerce) {
+            // Try to coerce the value
+            const coerced = coerceValue(value, type);
+            if (coerced.success) {
+                return {
+                    valid: true,
+                    value: coerced.value,
+                };
+            }
+        }
+        return {
+            valid: isValid,
+            value: isValid ? value : undefined,
+            errors: isValid ? undefined : [`Value is not a valid ${type}`],
+        };
+    }
+    // Use AI for complex type validation
+    const result = await generateObject({
+        model: 'sonnet',
+        schema: {
+            valid: 'Whether the value matches the expected type (boolean)',
+            errors: ['List of validation errors if invalid'],
+            coercedValue: coerce ? 'The value coerced to the expected type' : undefined,
+        },
+        system: `You are a type validation expert. Determine if a value matches an expected type.
+
+${coerce ? 'If the value can be coerced to the expected type, provide the coerced value.' : ''}
+${strict ? 'Be strict in your validation - require exact type matches.' : 'Be flexible - allow reasonable type conversions.'}`,
+        prompt: `Validate if this value matches the expected type:
+
+Value: ${JSON.stringify(value)}
+Type: ${type}
+
+Determine if the value is valid for this type.`,
+    });
+    const validation = result.object;
+    return {
+        valid: validation.valid,
+        value: coerce && validation.coercedValue !== undefined ? validation.coercedValue : value,
+        errors: validation.valid ? undefined : validation.errors,
+    };
+}
+/**
+ * Validate against a schema
+ */
+async function validateSchema(value, schema, options) {
+    const { coerce, strict } = options;
+    try {
+        // Convert SimpleSchema to Zod schema
+        const zodSchema = convertSchema(schema);
+        // Parse the value
+        const parsed = zodSchema.parse(value);
+        return {
+            valid: true,
+            value: parsed,
+        };
+    }
+    catch (error) {
+        if (strict) {
+            return {
+                valid: false,
+                errors: [error.message],
+            };
+        }
+        // Use AI for more flexible validation
+        const result = await generateObject({
+            model: 'sonnet',
+            schema: {
+                valid: 'Whether the value matches the schema (boolean)',
+                errors: ['List of validation errors'],
+                coercedValue: coerce ? 'The value with corrections/coercions applied' : undefined,
+            },
+            system: `You are a schema validation expert. Validate a value against a schema.
+
+${coerce ? 'Try to coerce the value to match the schema where reasonable.' : ''}
+Be helpful - provide clear error messages.`,
+            prompt: `Validate this value against the schema:
+
+Value:
+${JSON.stringify(value, null, 2)}
+
+Schema:
+${JSON.stringify(schema, null, 2)}
+
+Check if the value matches the schema structure and types.`,
+        });
+        const validation = result.object;
+        return {
+            valid: validation.valid,
+            value: coerce && validation.coercedValue !== undefined ? validation.coercedValue : value,
+            errors: validation.valid ? undefined : validation.errors,
+        };
+    }
+}
+/**
+ * Try to coerce a value to a specific type
+ */
+function coerceValue(value, type) {
+    try {
+        switch (type) {
+            case 'string':
+                return { success: true, value: String(value) };
+            case 'number':
+                const num = Number(value);
+                return { success: !isNaN(num), value: num };
+            case 'boolean':
+                if (typeof value === 'string') {
+                    const lower = value.toLowerCase();
+                    if (lower === 'true' || lower === '1') {
+                        return { success: true, value: true };
+                    }
+                    if (lower === 'false' || lower === '0') {
+                        return { success: true, value: false };
+                    }
+                }
+                return { success: true, value: Boolean(value) };
+            case 'array':
+                if (Array.isArray(value)) {
+                    return { success: true, value };
+                }
+                return { success: true, value: [value] };
+            default:
+                return { success: false };
+        }
+    }
+    catch {
+        return { success: false };
+    }
+}
+/**
+ * Check if a value is valid email
+ *
+ * @param value - Value to check
+ * @returns Promise resolving to validation result
+ *
+ * @example
+ * ```ts
+ * const result = await is.email('test@example.com')
+ * console.log(result.valid) // true
+ * ```
+ */
+is.email = async (value) => {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    const valid = typeof value === 'string' && emailRegex.test(value);
+    return {
+        valid,
+        value: valid ? value : undefined,
+        errors: valid ? undefined : ['Invalid email format'],
+    };
+};
+/**
+ * Check if a value is a valid URL
+ *
+ * @param value - Value to check
+ * @returns Promise resolving to validation result
+ */
+is.url = async (value) => {
+    try {
+        if (typeof value !== 'string') {
+            return {
+                valid: false,
+                errors: ['Value must be a string'],
+            };
+        }
+        new URL(value);
+        return {
+            valid: true,
+            value,
+        };
+    }
+    catch {
+        return {
+            valid: false,
+            errors: ['Invalid URL format'],
+        };
+    }
+};
+/**
+ * Check if a value is a valid date
+ *
+ * @param value - Value to check
+ * @param options - Validation options
+ * @returns Promise resolving to validation result
+ */
+is.date = async (value, options = {}) => {
+    const { coerce } = options;
+    if (value instanceof Date) {
+        return {
+            valid: !isNaN(value.getTime()),
+            value,
+            errors: isNaN(value.getTime()) ? ['Invalid date'] : undefined,
+        };
+    }
+    if (coerce) {
+        try {
+            const date = new Date(value);
+            if (!isNaN(date.getTime())) {
+                return {
+                    valid: true,
+                    value: date,
+                };
+            }
+        }
+        catch {
+            // Fall through to invalid
+        }
+    }
+    return {
+        valid: false,
+        errors: ['Invalid date'],
+    };
+};
+/**
+ * Check if a value matches a custom validation function
+ *
+ * @param value - Value to check
+ * @param validator - Validation function
+ * @returns Promise resolving to validation result
+ *
+ * @example
+ * ```ts
+ * const result = await is.custom(
+ *   42,
+ *   (v) => typeof v === 'number' && v > 0 && v < 100
+ * )
+ * ```
+ */
+is.custom = async (value, validator) => {
+    try {
+        const valid = await validator(value);
+        return {
+            valid,
+            value: valid ? value : undefined,
+            errors: valid ? undefined : ['Custom validation failed'],
+        };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            errors: [error.message],
+        };
+    }
+};

package/src/kpis.js

@@ -0,0 +1,270 @@
+/**
+ * KPI and OKR tracking functionality for digital workers
+ */
+export function kpis(definition) {
+    return definition;
+}
+/**
+ * Update a KPI's current value
+ *
+ * @param kpi - The KPI to update
+ * @param current - New current value
+ * @returns Updated KPI
+ *
+ * @example
+ * ```ts
+ * const updated = kpis.update(deploymentFrequency, 8)
+ * console.log(updated.current) // 8
+ * console.log(updated.trend) // 'up' (automatically determined)
+ * ```
+ */
+kpis.update = (kpi, current) => {
+    // Determine trend
+    let trend = 'stable';
+    if (current > kpi.current) {
+        trend = 'up';
+    }
+    else if (current < kpi.current) {
+        trend = 'down';
+    }
+    return {
+        ...kpi,
+        current,
+        trend,
+    };
+};
+/**
+ * Calculate progress towards target (0-1)
+ *
+ * @param kpi - The KPI
+ * @returns Progress as a decimal (0-1)
+ *
+ * @example
+ * ```ts
+ * const kpi = { current: 75, target: 100 }
+ * const progress = kpis.progress(kpi) // 0.75
+ * ```
+ */
+kpis.progress = (kpi) => {
+    if (kpi.target === 0)
+        return 0;
+    return Math.min(1, Math.max(0, kpi.current / kpi.target));
+};
+/**
+ * Check if a KPI is on track
+ *
+ * @param kpi - The KPI
+ * @param threshold - Minimum progress to be "on track" (default: 0.8)
+ * @returns Whether the KPI is on track
+ *
+ * @example
+ * ```ts
+ * const kpi = { current: 85, target: 100 }
+ * const onTrack = kpis.onTrack(kpi) // true (85% >= 80%)
+ * ```
+ */
+kpis.onTrack = (kpi, threshold = 0.8) => {
+    return kpis.progress(kpi) >= threshold;
+};
+/**
+ * Get the gap to target
+ *
+ * @param kpi - The KPI
+ * @returns Difference between target and current
+ *
+ * @example
+ * ```ts
+ * const kpi = { current: 75, target: 100 }
+ * const gap = kpis.gap(kpi) // 25
+ * ```
+ */
+kpis.gap = (kpi) => {
+    return kpi.target - kpi.current;
+};
+/**
+ * Format a KPI for display
+ *
+ * @param kpi - The KPI
+ * @returns Formatted string
+ *
+ * @example
+ * ```ts
+ * const kpi = {
+ *   name: 'Deployment Frequency',
+ *   current: 5,
+ *   target: 10,
+ *   unit: 'deploys/week',
+ *   trend: 'up',
+ * }
+ * const formatted = kpis.format(kpi)
+ * // "Deployment Frequency: 5/10 deploys/week (50%, trending up)"
+ * ```
+ */
+kpis.format = (kpi) => {
+    const progress = kpis.progress(kpi);
+    const progressPercent = Math.round(progress * 100);
+    const trendEmoji = kpi.trend === 'up' ? '↑' : kpi.trend === 'down' ? '↓' : '→';
+    return `${kpi.name}: ${kpi.current}/${kpi.target} ${kpi.unit} (${progressPercent}%, trending ${kpi.trend} ${trendEmoji})`;
+};
+/**
+ * Compare two KPI snapshots to see change over time
+ *
+ * @param previous - Previous KPI state
+ * @param current - Current KPI state
+ * @returns Change analysis
+ *
+ * @example
+ * ```ts
+ * const change = kpis.compare(previousKPI, currentKPI)
+ * console.log(change.delta) // 5
+ * console.log(change.percentChange) // 10
+ * console.log(change.improved) // true
+ * ```
+ */
+kpis.compare = (previous, current) => {
+    const delta = current.current - previous.current;
+    const percentChange = previous.current !== 0
+        ? (delta / previous.current) * 100
+        : 0;
+    // Improved if we got closer to the target
+    const previousGap = Math.abs(previous.target - previous.current);
+    const currentGap = Math.abs(current.target - current.current);
+    const improved = currentGap < previousGap;
+    return {
+        delta,
+        percentChange,
+        improved,
+    };
+};
+/**
+ * Define OKRs (Objectives and Key Results)
+ *
+ * @param definition - OKR definition
+ * @returns The defined OKR
+ *
+ * @example
+ * ```ts
+ * const engineeringOKR = okrs({
+ *   objective: 'Improve development velocity',
+ *   keyResults: [
+ *     {
+ *       name: 'Deployment Frequency',
+ *       current: 5,
+ *       target: 10,
+ *       unit: 'deploys/week',
+ *     },
+ *     {
+ *       name: 'Lead Time',
+ *       current: 48,
+ *       target: 24,
+ *       unit: 'hours',
+ *     },
+ *     {
+ *       name: 'Change Failure Rate',
+ *       current: 15,
+ *       target: 5,
+ *       unit: '%',
+ *     },
+ *   ],
+ *   owner: 'engineering-team',
+ *   dueDate: new Date('2024-03-31'),
+ * })
+ * ```
+ */
+export function okrs(definition) {
+    return definition;
+}
+/**
+ * Calculate overall OKR progress
+ *
+ * @param okr - The OKR
+ * @returns Average progress across all key results (0-1)
+ *
+ * @example
+ * ```ts
+ * const progress = okrs.progress(engineeringOKR)
+ * console.log(progress) // 0.67 (67% complete)
+ * ```
+ */
+okrs.progress = (okr) => {
+    if (okr.keyResults.length === 0)
+        return 0;
+    const totalProgress = okr.keyResults.reduce((sum, kr) => {
+        return sum + kpis.progress(kr);
+    }, 0);
+    return totalProgress / okr.keyResults.length;
+};
+/**
+ * Update a key result in an OKR
+ *
+ * @param okr - The OKR
+ * @param keyResultName - Name of key result to update
+ * @param current - New current value
+ * @returns Updated OKR
+ *
+ * @example
+ * ```ts
+ * const updated = okrs.updateKeyResult(
+ *   engineeringOKR,
+ *   'Deployment Frequency',
+ *   8
+ * )
+ * ```
+ */
+okrs.updateKeyResult = (okr, keyResultName, current) => {
+    return {
+        ...okr,
+        keyResults: okr.keyResults.map((kr) => kr.name === keyResultName ? { ...kr, current } : kr),
+        progress: undefined, // Will be recalculated
+    };
+};
+/**
+ * Check if OKR is on track
+ *
+ * @param okr - The OKR
+ * @param threshold - Minimum progress to be "on track" (default: 0.7)
+ * @returns Whether the OKR is on track
+ *
+ * @example
+ * ```ts
+ * const onTrack = okrs.onTrack(engineeringOKR)
+ * ```
+ */
+okrs.onTrack = (okr, threshold = 0.7) => {
+    return okrs.progress(okr) >= threshold;
+};
+/**
+ * Format OKR for display
+ *
+ * @param okr - The OKR
+ * @returns Formatted string
+ *
+ * @example
+ * ```ts
+ * const formatted = okrs.format(engineeringOKR)
+ * console.log(formatted)
+ * // Improve development velocity (67% complete)
+ * // • Deployment Frequency: 5/10 deploys/week (50%)
+ * // • Lead Time: 48/24 hours (200%)
+ * // • Change Failure Rate: 15/5 % (300%)
+ * ```
+ */
+okrs.format = (okr) => {
+    const progress = okrs.progress(okr);
+    const progressPercent = Math.round(progress * 100);
+    const lines = [
+        `${okr.objective} (${progressPercent}% complete)`,
+        ...okr.keyResults.map((kr) => {
+            const krProgress = kpis.progress(kr);
+            const krPercent = Math.round(krProgress * 100);
+            return `  • ${kr.name}: ${kr.current}/${kr.target} ${kr.unit} (${krPercent}%)`;
+        }),
+    ];
+    if (okr.owner) {
+        lines.push(`  Owner: ${okr.owner}`);
+    }
+    if (okr.dueDate) {
+        lines.push(`  Due: ${okr.dueDate.toLocaleDateString()}`);
+    }
+    return lines.join('\n');
+};