@probelabs/visor 0.1.106 → 0.1.111

package/dist/examples/calculator-json-output-guide.md

@@ -0,0 +1,311 @@
+# Calculator SDK - JSON Output Guide
+
+This guide explains how to use the calculator examples with JSON output for programmatic processing.
+
+## Overview
+
+Three calculator variants are provided:
+
+1. **`calculator-sdk-real.ts`** - Interactive with table output (original)
+2. **`calculator-sdk-json.ts`** - Interactive with JSON output + custom visualization
+3. **`calculator-sdk-automated.ts`** - Non-interactive with pure JSON output
+
+## Quick Start
+
+### Interactive with JSON Output
+
+```bash
+bun examples/calculator-sdk-json.ts
+```
+
+**Features:**
+- Prompts for user input
+- Uses `outputFormat: 'json'`
+- Suppresses engine console output
+- Returns structured JSON
+- Custom visualization in script
+
+**Output:**
+```json
+{
+  "success": true,
+  "calculation": {
+    "number1": 10,
+    "number2": 5,
+    "operation": "+",
+    "result": 15,
+    "expression": "10 + 5 = 15"
+  },
+  "executionTime": 1234,
+  "issues": []
+}
+```
+
+### Fully Automated (No Interaction)
+
+```bash
+# With default values (10 + 5)
+bun examples/calculator-sdk-automated.ts
+
+# With custom values
+bun examples/calculator-sdk-automated.ts 100 25 -
+
+# Output is pure JSON
+bun examples/calculator-sdk-automated.ts 7 8 '*' --json
+```
+
+**Features:**
+- No user interaction required
+- Inputs provided programmatically
+- All console output suppressed
+- Perfect for testing & automation
+- Includes test suite
+
+## Key Techniques
+
+### 1. Using JSON Output Format
+
+```typescript
+const result = await engine.executeChecks({
+  checks: checksToRun,
+  config: calculatorConfig,
+  outputFormat: 'json',  // ← Instead of 'table'
+  maxParallelism: 1,
+  debug: false
+});
+```
+
+### 2. Suppressing Console Output
+
+```typescript
+function suppressAllOutput() {
+  const noop = () => {};
+  const originalLog = console.log;
+  // ... save all console methods
+
+  console.log = noop;
+  console.error = noop;
+  console.warn = noop;
+  // ... suppress all
+
+  return {
+    restore: () => {
+      console.log = originalLog;
+      // ... restore all
+    }
+  };
+}
+
+// Usage
+const suppressor = suppressAllOutput();
+const result = await engine.executeChecks({...});
+suppressor.restore();
+```
+
+### 3. Automated Input Provider
+
+```typescript
+function createAutomatedInputHandler(inputs: {
+  'get-number1': string;
+  'get-number2': string;
+  'get-operation': string;
+}) {
+  return async (request: HumanInputRequest): Promise<string> => {
+    return inputs[request.checkId];
+  };
+}
+
+// Set the hook
+HumanInputCheckProvider.setHooks({
+  onHumanInput: createAutomatedInputHandler({
+    'get-number1': '10',
+    'get-number2': '5',
+    'get-operation': '+'
+  })
+});
+```
+
+### 4. Accessing Memory Results
+
+```typescript
+const { MemoryStore } = await import('../src/memory-store');
+const memoryStore = MemoryStore.getInstance(config.memory);
+
+const result = memoryStore.get('result', 'calculator');
+const num1 = memoryStore.get('number1', 'calculator');
+```
+
+## JSON Output Structure
+
+The result from `executeChecks` with `outputFormat: 'json'` returns:
+
+```typescript
+interface ExecutionResult {
+  executionTime: number;
+  timestamp: string;
+  summary: {
+    issues: Array<{
+      file: string;
+      line: number;
+      ruleId: string;
+      message: string;
+      severity: 'info' | 'warning' | 'error' | 'critical';
+      category: string;
+    }>;
+  };
+  // Additional fields based on output format
+}
+```
+
+## Custom Result Structure
+
+You can transform this into your own structure:
+
+```typescript
+interface CalculationResult {
+  success: boolean;
+  calculation?: {
+    number1: number;
+    number2: number;
+    operation: string;
+    result: number;
+    expression: string;
+  };
+  executionTime?: number;
+  issues?: any[];
+  error?: string;
+}
+
+async function calculate(num1, num2, op): Promise<CalculationResult> {
+  // Suppress output
+  const suppressor = suppressAllOutput();
+
+  // Execute
+  const result = await engine.executeChecks({
+    outputFormat: 'json',
+    // ...
+  });
+
+  suppressor.restore();
+
+  // Extract from memory
+  const memoryStore = MemoryStore.getInstance();
+  const resultValue = memoryStore.get('result', 'calculator');
+
+  // Return custom structure
+  return {
+    success: true,
+    calculation: {
+      number1: parseFloat(num1),
+      number2: parseFloat(num2),
+      operation: op,
+      result: resultValue,
+      expression: `${num1} ${op} ${num2} = ${resultValue}`
+    },
+    executionTime: result.executionTime,
+    issues: result.summary?.issues || []
+  };
+}
+```
+
+## Testing Example
+
+```typescript
+// Run multiple calculations programmatically
+const testCases = [
+  { num1: '100', num2: '25', operation: '-', expected: 75 },
+  { num1: '7', num2: '8', operation: '*', expected: 56 },
+  { num1: '100', num2: '4', operation: '/', expected: 25 },
+];
+
+const results = await Promise.all(
+  testCases.map(tc =>
+    calculate(tc.num1, tc.num2, tc.operation, { suppressOutput: true })
+  )
+);
+
+// Verify results
+results.forEach((result, idx) => {
+  const tc = testCases[idx];
+  const passed = result.calculation?.result === tc.expected;
+  console.log(`${tc.num1} ${tc.operation} ${tc.num2} = ${result.calculation?.result} ${passed ? '✅' : '❌'}`);
+});
+```
+
+## Benefits
+
+### For Production Use
+- ✅ Clean JSON output for APIs
+- ✅ No stdout pollution
+- ✅ Easy to parse and process
+- ✅ Structured error handling
+
+### For Testing
+- ✅ Automated test suites
+- ✅ CI/CD integration
+- ✅ Reproducible results
+- ✅ No user interaction needed
+
+### For Monitoring
+- ✅ Log to files/databases
+- ✅ Metrics collection
+- ✅ Alerting on failures
+- ✅ Performance tracking
+
+## Integration Examples
+
+### Express API Endpoint
+
+```typescript
+app.post('/api/calculate', async (req, res) => {
+  const { num1, num2, operation } = req.body;
+
+  const result = await calculate(num1, num2, operation, {
+    suppressOutput: true
+  });
+
+  if (result.success) {
+    res.json(result);
+  } else {
+    res.status(400).json({ error: result.error });
+  }
+});
+```
+
+### CLI Tool with JSON Flag
+
+```typescript
+if (process.argv.includes('--json')) {
+  const result = await calculate(num1, num2, op, { suppressOutput: true });
+  console.log(JSON.stringify(result));
+} else {
+  // Interactive mode
+  await interactiveCalculator();
+}
+```
+
+### Background Job
+
+```typescript
+async function processCalculations(jobs: CalculationJob[]) {
+  const results = await Promise.all(
+    jobs.map(job =>
+      calculate(job.num1, job.num2, job.operation, {
+        suppressOutput: true
+      })
+    )
+  );
+
+  // Store results in database
+  await db.calculations.insertMany(results);
+
+  return results;
+}
+```
+
+## See Also
+
+- **SDK Documentation**: `docs/sdk.md`
+- **Human Input Feature**: `docs/human-input-feature-plan.md`
+- **Memory Provider**: `src/providers/memory-check-provider.ts`
+- **Examples**: `examples/calculator-*.ts`

package/dist/examples/calculator-sdk-automated.ts

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+
+/**
+ * Calculator SDK - Fully Automated (Non-Interactive)
+ *
+ * This example shows how to:
+ * - Run calculations without user interaction
+ * - Provide inputs programmatically
+ * - Get pure JSON output
+ * - Use for testing or automation
+ *
+ * Usage:
+ *   npm run build
+ *   bun examples/calculator-sdk-automated.ts
+ *   bun examples/calculator-sdk-automated.ts 10 5 +
+ */
+
+import { HumanInputRequest, VisorConfig } from '../src/types/config';
+import { HumanInputCheckProvider } from '../src/providers/human-input-check-provider';
+import { CheckExecutionEngine } from '../src/check-execution-engine';
+
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+
+const calculatorConfig: VisorConfig = {
+  version: "1.0",
+
+  memory: {
+    namespace: "calculator",
+    persist: false
+  },
+
+  checks: {
+    "get-number1": {
+      type: "human-input",
+      prompt: "Enter the first number:",
+    },
+
+    "store-number1": {
+      type: "memory",
+      depends_on: ["get-number1"],
+      operation: "set",
+      namespace: "calculator",
+      key: "number1",
+      value_js: "parseFloat(outputs['get-number1'])"
+    },
+
+    "get-number2": {
+      type: "human-input",
+      depends_on: ["store-number1"],
+      prompt: "Enter the second number:",
+    },
+
+    "store-number2": {
+      type: "memory",
+      depends_on: ["get-number2"],
+      operation: "set",
+      namespace: "calculator",
+      key: "number2",
+      value_js: "parseFloat(outputs['get-number2'])"
+    },
+
+    "get-operation": {
+      type: "human-input",
+      depends_on: ["store-number2"],
+      prompt: "Select operation (+, -, *, /):",
+    },
+
+    "store-operation": {
+      type: "memory",
+      depends_on: ["get-operation"],
+      operation: "set",
+      namespace: "calculator",
+      key: "operation",
+      value_js: "outputs['get-operation'].trim()",
+      fail_if: "!['+', '-', '*', '/'].includes(outputs['get-operation'].trim())"
+    },
+
+    "calculate": {
+      type: "script",
+      depends_on: ["store-operation"],
+      content: `
+        const num1 = memory.get('number1', 'calculator');
+        const num2 = memory.get('number2', 'calculator');
+        const op = memory.get('operation', 'calculator');
+
+        let result;
+        switch(op) {
+          case '+': result = num1 + num2; break;
+          case '-': result = num1 - num2; break;
+          case '*': result = num1 * num2; break;
+          case '/':
+            if (num2 === 0) throw new Error('Division by zero!');
+            result = num1 / num2;
+            break;
+          default: throw new Error('Invalid operation: ' + op);
+        }
+
+        return result;
+      `
+    }
+  }
+};
+
+// ============================================================================
+// AUTOMATED INPUT PROVIDER
+// ============================================================================
+
+interface CalculatorInputs {
+  'get-number1': string;
+  'get-number2': string;
+  'get-operation': string;
+}
+
+/**
+ * Create an automated input handler with predefined values
+ */
+function createAutomatedInputHandler(inputs: CalculatorInputs) {
+  return async (request: HumanInputRequest): Promise<string> => {
+    const checkId = request.checkId as keyof CalculatorInputs;
+    const value = inputs[checkId];
+
+    if (value === undefined) {
+      throw new Error(`No automated input provided for check: ${checkId}`);
+    }
+
+    return value;
+  };
+}
+
+// ============================================================================
+// SUPPRESS ALL CONSOLE OUTPUT
+// ============================================================================
+
+function suppressAllOutput() {
+  const noop = () => {};
+  const originalLog = console.log;
+  const originalError = console.error;
+  const originalWarn = console.warn;
+  const originalInfo = console.info;
+  const originalDebug = console.debug;
+
+  console.log = noop;
+  console.error = noop;
+  console.warn = noop;
+  console.info = noop;
+  console.debug = noop;
+
+  return {
+    restore: () => {
+      console.log = originalLog;
+      console.error = originalError;
+      console.warn = originalWarn;
+      console.info = originalInfo;
+      console.debug = originalDebug;
+    }
+  };
+}
+
+// ============================================================================
+// CALCULATION FUNCTION
+// ============================================================================
+
+interface CalculationResult {
+  success: boolean;
+  calculation?: {
+    number1: number;
+    number2: number;
+    operation: string;
+    result: number;
+    expression: string;
+  };
+  executionTime?: number;
+  issues?: any[];
+  error?: string;
+}
+
+async function calculate(
+  num1: string,
+  num2: string,
+  operation: string,
+  options: { verbose?: boolean; suppressOutput?: boolean } = {}
+): Promise<CalculationResult> {
+  const { verbose = false, suppressOutput = true } = options;
+
+  try {
+    // Set up automated inputs
+    HumanInputCheckProvider.setHooks({
+      onHumanInput: createAutomatedInputHandler({
+        'get-number1': num1,
+        'get-number2': num2,
+        'get-operation': operation
+      })
+    });
+
+    // Suppress console output if requested
+    const suppressor = suppressOutput ? suppressAllOutput() : null;
+
+    // Create execution engine
+    const engine = new CheckExecutionEngine();
+
+    // Execute all checks
+    const checksToRun = Object.keys(calculatorConfig.checks || {});
+
+    const result = await engine.executeChecks({
+      checks: checksToRun,
+      config: calculatorConfig,
+      outputFormat: 'json',
+      maxParallelism: 1,
+      debug: false
+    });
+
+    // Restore console
+    if (suppressor) suppressor.restore();
+
+    // Extract results from memory
+    const { MemoryStore } = await import('../src/memory-store');
+    const memoryStore = MemoryStore.getInstance(calculatorConfig.memory);
+
+    const n1 = memoryStore.get('number1', 'calculator');
+    const n2 = memoryStore.get('number2', 'calculator');
+    const op = memoryStore.get('operation', 'calculator');
+    const resultValue = memoryStore.get('result', 'calculator');
+
+    return {
+      success: true,
+      calculation: {
+        number1: n1,
+        number2: n2,
+        operation: op,
+        result: resultValue,
+        expression: `${n1} ${op} ${n2} = ${resultValue}`
+      },
+      executionTime: result.executionTime,
+      issues: result.summary?.issues || []
+    };
+
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+// ============================================================================
+// MAIN EXECUTION
+// ============================================================================
+
+async function main() {
+  // Parse command line arguments
+  const args = process.argv.slice(2);
+
+  let num1: string, num2: string, operation: string;
+
+  if (args.length >= 3) {
+    // Use command line arguments
+    [num1, num2, operation] = args;
+  } else {
+    // Use default values for demo
+    num1 = '10';
+    num2 = '5';
+    operation = '+';
+  }
+
+  console.log('🧮 Calculator SDK - Automated Mode\n');
+  console.log(`Input: ${num1} ${operation} ${num2}\n`);
+
+  // Run calculation
+  const result = await calculate(num1, num2, operation, {
+    verbose: false,
+    suppressOutput: true
+  });
+
+  // Display result
+  if (result.success && result.calculation) {
+    console.log('✅ Calculation Complete!\n');
+    console.log('📊 Result (JSON):\n');
+    console.log(JSON.stringify(result, null, 2));
+
+    console.log('\n' + '─'.repeat(50));
+    console.log('Expression:', result.calculation.expression);
+    console.log('─'.repeat(50));
+
+    if (result.issues && result.issues.length > 0) {
+      console.log(`\n⚠️  ${result.issues.length} issue(s) found`);
+    }
+  } else {
+    console.log('❌ Calculation Failed!\n');
+    console.log('Error:', result.error);
+  }
+
+  console.log();
+
+  // Run additional test cases
+  console.log('🧪 Running Test Cases...\n');
+
+  const testCases = [
+    { num1: '100', num2: '25', operation: '-', expected: 75 },
+    { num1: '7', num2: '8', operation: '*', expected: 56 },
+    { num1: '100', num2: '4', operation: '/', expected: 25 },
+    { num1: '15', num2: '3', operation: '+', expected: 18 },
+  ];
+
+  const results = await Promise.all(
+    testCases.map(tc =>
+      calculate(tc.num1, tc.num2, tc.operation, { suppressOutput: true })
+    )
+  );
+
+  console.log('Test Results:');
+  console.log('─'.repeat(70));
+  console.log('Input'.padEnd(20), 'Expected'.padEnd(15), 'Actual'.padEnd(15), 'Status');
+  console.log('─'.repeat(70));
+
+  results.forEach((result, idx) => {
+    const tc = testCases[idx];
+    const input = `${tc.num1} ${tc.operation} ${tc.num2}`;
+    const expected = tc.expected;
+    const actual = result.calculation?.result;
+    const status = actual === expected ? '✅ PASS' : '❌ FAIL';
+
+    console.log(
+      input.padEnd(20),
+      String(expected).padEnd(15),
+      String(actual).padEnd(15),
+      status
+    );
+  });
+
+  console.log('─'.repeat(70));
+  console.log('\n✨ Done!\n');
+}
+
+// Run main
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});