digital-workers 0.1.1 → 2.0.2

package/src/is.ts

@@ -0,0 +1,372 @@
+/**
+ * Type validation and checking functionality for digital workers
+ */
+
+import { generateObject } from 'ai-functions'
+import { schema as convertSchema, type SimpleSchema } from 'ai-functions'
+import type { TypeCheckResult, IsOptions } from './types.js'
+
+/**
+ * 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: unknown,
+  type: string | SimpleSchema,
+  options: IsOptions = {}
+): Promise<TypeCheckResult> {
+  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: unknown,
+  type: string,
+  options: IsOptions
+): Promise<TypeCheckResult> {
+  const { coerce, strict } = options
+
+  // Built-in JavaScript types
+  const builtInTypes: Record<string, (v: unknown) => boolean> = {
+    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 as unknown as {
+    valid: boolean
+    errors: string[]
+    coercedValue?: unknown
+  }
+
+  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: unknown,
+  schema: SimpleSchema,
+  options: IsOptions
+): Promise<TypeCheckResult> {
+  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 as 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 as unknown as {
+      valid: boolean
+      errors: string[]
+      coercedValue?: unknown
+    }
+
+    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: unknown,
+  type: string
+): { success: boolean; value?: unknown } {
+  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: unknown): Promise<TypeCheckResult> => {
+  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: unknown): Promise<TypeCheckResult> => {
+  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: unknown, options: IsOptions = {}): Promise<TypeCheckResult> => {
+  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 as string | number)
+      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: unknown,
+  validator: (v: unknown) => boolean | Promise<boolean>
+): Promise<TypeCheckResult> => {
+  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 as Error).message],
+    }
+  }
+}

package/src/kpis.ts

@@ -0,0 +1,348 @@
+/**
+ * KPI and OKR tracking functionality for digital workers
+ */
+
+import type { KPI, OKR } from './types.js'
+
+/**
+ * Define and track Key Performance Indicators
+ *
+ * @param definition - KPI definition or array of KPIs
+ * @returns The defined KPI(s)
+ *
+ * @example
+ * ```ts
+ * const deploymentFrequency = kpis({
+ *   name: 'Deployment Frequency',
+ *   description: 'Number of deployments per week',
+ *   current: 5,
+ *   target: 10,
+ *   unit: 'deploys/week',
+ *   trend: 'up',
+ *   period: 'weekly',
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Define multiple KPIs
+ * const teamKPIs = kpis([
+ *   {
+ *     name: 'Code Quality',
+ *     description: 'SonarQube quality score',
+ *     current: 85,
+ *     target: 90,
+ *     unit: 'score',
+ *     trend: 'up',
+ *   },
+ *   {
+ *     name: 'Test Coverage',
+ *     description: 'Percentage of code covered by tests',
+ *     current: 75,
+ *     target: 80,
+ *     unit: '%',
+ *     trend: 'up',
+ *   },
+ * ])
+ * ```
+ */
+export function kpis(definition: KPI): KPI
+export function kpis(definition: KPI[]): KPI[]
+export function kpis(definition: KPI | KPI[]): KPI | KPI[] {
+  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: KPI, current: number): KPI => {
+  // Determine trend
+  let trend: KPI['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: Pick<KPI, 'current' | 'target'>): number => {
+  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: Pick<KPI, 'current' | 'target'>, threshold = 0.8): boolean => {
+  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: Pick<KPI, 'current' | 'target'>): number => {
+  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: KPI): string => {
+  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: Pick<KPI, 'current' | 'target'>,
+  current: Pick<KPI, 'current' | 'target'>
+): {
+  delta: number
+  percentChange: number
+  improved: boolean
+} => {
+  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: OKR): OKR {
+  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: OKR): number => {
+  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: OKR,
+  keyResultName: string,
+  current: number
+): OKR => {
+  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: OKR, threshold = 0.7): boolean => {
+  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: OKR): string => {
+  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')
+}