icdev 0.0.3__py3-none-any.whl

tools/embedded/crash_analyzer.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+"""Crash dump analyzer for FreeRTOS self-healing.
+
+Analyzes HardFault, stack overflow, watchdog, and assertion failures.
+Matches against known embedded patterns and generates fix suggestions.
+
+Usage:
+    python tools/embedded/crash_analyzer.py --crash-type hardfault --device-id dev-001 --json
+    python tools/embedded/crash_analyzer.py --analyze --crash-id crash-001 --json
+    python tools/embedded/crash_analyzer.py --patterns --json
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from tools.db.storage import get_connection
+
+
+# Known crash patterns — deterministic matching (air-gap safe)
+CRASH_PATTERNS = {
+    "stack_overflow_task": {
+        "match": ["stack overflow", "StackType_t", "pxTopOfStack"],
+        "root_cause": "Task stack too small for its workload",
+        "fix": "Increase stack size in xTaskCreate() — check stack watermark with uxTaskGetStackHighWaterMark()",
+        "severity": "critical",
+        "auto_healable": True,
+        "fix_template": "Increase configMINIMAL_STACK_SIZE or task-specific stack allocation by 2x",
+    },
+    "hardfault_null_ptr": {
+        "match": ["hardfault", "0x00000000", "null pointer", "BusFault"],
+        "root_cause": "Null pointer dereference — accessing address 0x0",
+        "fix": "Add null checks before pointer dereference. Check task notification/queue receive return values.",
+        "severity": "critical",
+        "auto_healable": False,
+    },
+    "hardfault_alignment": {
+        "match": ["hardfault", "UsageFault", "UNALIGNED"],
+        "root_cause": "Unaligned memory access on Cortex-M with strict alignment",
+        "fix": "Use __attribute__((packed)) or memcpy for unaligned struct access",
+        "severity": "high",
+        "auto_healable": False,
+    },
+    "heap_exhaustion": {
+        "match": ["malloc failed", "pvPortMalloc", "heap", "configTOTAL_HEAP_SIZE"],
+        "root_cause": "FreeRTOS heap exhausted — too many allocations or memory leak",
+        "fix": "Increase configTOTAL_HEAP_SIZE, use static allocation, or find memory leak",
+        "severity": "critical",
+        "auto_healable": True,
+        "fix_template": "Increase configTOTAL_HEAP_SIZE by 50% in FreeRTOSConfig.h",
+    },
+    "watchdog_timeout": {
+        "match": ["watchdog", "wdt", "timeout", "iwdg"],
+        "root_cause": "Task blocked too long — missed watchdog feed deadline",
+        "fix": "Check for infinite loops, blocked I/O, or priority inversion. Add watchdog feeds in long operations.",
+        "severity": "high",
+        "auto_healable": False,
+    },
+    "assertion_failure": {
+        "match": ["assert", "configASSERT", "assertion failed"],
+        "root_cause": "FreeRTOS kernel assertion — usually invalid parameters or ISR misuse",
+        "fix": "Check if calling FreeRTOS API from wrong context (ISR vs task). Use FromISR variants in interrupts.",
+        "severity": "high",
+        "auto_healable": False,
+    },
+    "mqtt_disconnect": {
+        "match": ["mqtt", "disconnect", "CONNACK", "keepalive"],
+        "root_cause": "MQTT broker connection lost — network issue or keepalive timeout",
+        "fix": "Implement reconnection logic with exponential backoff in MQTT task",
+        "severity": "medium",
+        "auto_healable": True,
+        "fix_template": "Add reconnect with 1s/2s/4s/8s/16s backoff in sparkpilot_mqtt_task()",
+    },
+    "memory_corruption": {
+        "match": ["corruption", "overwrite", "buffer overflow", "canary"],
+        "root_cause": "Memory corruption — buffer overflow or use-after-free",
+        "fix": "Enable stack canaries, use bounded string functions (snprintf, strlcpy), check array bounds",
+        "severity": "critical",
+        "auto_healable": False,
+    },
+}
+
+
+def _now():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def analyze_crash(crash_type: str, device_id: str, stack_trace: str = "",
+                  registers: dict | None = None, firmware_version: str = "") -> dict:
+    """Analyze a crash dump and match against known patterns."""
+    search_text = f"{crash_type} {stack_trace}".lower()
+
+    matched_patterns = []
+    for pattern_id, pattern in CRASH_PATTERNS.items():
+        score = sum(1 for kw in pattern["match"] if kw.lower() in search_text)
+        if score > 0:
+            matched_patterns.append({
+                "pattern_id": pattern_id,
+                "match_score": score,
+                "root_cause": pattern["root_cause"],
+                "fix": pattern["fix"],
+                "severity": pattern["severity"],
+                "auto_healable": pattern.get("auto_healable", False),
+                "fix_template": pattern.get("fix_template"),
+            })
+
+    matched_patterns.sort(key=lambda x: x["match_score"], reverse=True)
+
+    best_match = matched_patterns[0] if matched_patterns else None
+    confidence = min(1.0, (best_match["match_score"] / 3.0)) if best_match else 0.0
+
+    crash_id = f"crash-{uuid.uuid4().hex[:8]}"
+    analysis = {
+        "crash_id": crash_id,
+        "device_id": device_id,
+        "crash_type": crash_type,
+        "matched_patterns": matched_patterns[:3],
+        "best_match": best_match,
+        "confidence": confidence,
+        "auto_healable": best_match["auto_healable"] if best_match else False,
+        "recommendation": "auto_fix" if confidence >= 0.7 and best_match and best_match["auto_healable"]
+                          else "suggest_fix" if confidence >= 0.3
+                          else "escalate",
+    }
+
+    # Store in DB
+    conn = get_connection()
+    try:
+        conn.execute(
+            "INSERT INTO crash_dump_log "
+            "(id, device_id, crash_type, stack_trace, registers, firmware_version, "
+            "analysis, root_cause, auto_healed) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (crash_id, device_id, crash_type, stack_trace,
+             json.dumps(registers or {}), firmware_version,
+             json.dumps(analysis), best_match["root_cause"] if best_match else "unknown",
+             1 if analysis["recommendation"] == "auto_fix" else 0),
+        )
+        conn.commit()
+    except Exception:
+        pass
+    finally:
+        conn.close()
+
+    return analysis
+
+
+def list_patterns() -> dict:
+    """List all known crash patterns."""
+    return {
+        "status": "success",
+        "pattern_count": len(CRASH_PATTERNS),
+        "patterns": [
+            {"id": k, "severity": v["severity"], "auto_healable": v.get("auto_healable", False),
+             "root_cause": v["root_cause"]}
+            for k, v in CRASH_PATTERNS.items()
+        ],
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Crash Dump Analyzer")
+    parser.add_argument("--crash-type", help="Crash type (hardfault, stack_overflow, watchdog, etc.)")
+    parser.add_argument("--device-id", default="dev-sim", help="Device ID")
+    parser.add_argument("--stack-trace", default="", help="Stack trace text")
+    parser.add_argument("--firmware-version", default="", help="Firmware version")
+    parser.add_argument("--analyze", action="store_true", help="Analyze a crash")
+    parser.add_argument("--patterns", action="store_true", help="List known patterns")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    if args.patterns:
+        result = list_patterns()
+    elif args.crash_type:
+        result = analyze_crash(args.crash_type, args.device_id, args.stack_trace,
+                               firmware_version=args.firmware_version)
+    else:
+        parser.print_help()
+        return
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

tools/embedded/nl_to_firmware.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+"""Natural Language to Firmware generator.
+
+Translates natural language commands (e.g., 'Blink the LED every 2 seconds')
+into FreeRTOS C code, cross-compiles, and optionally deploys via OTA or simulator.
+
+Usage:
+    python tools/embedded/nl_to_firmware.py --command "Blink LED every 2 seconds" --board esp32-s3 --json
+    python tools/embedded/nl_to_firmware.py --command "Read temperature sensor" --board simulator --json
+    python tools/embedded/nl_to_firmware.py --command "Send MQTT message every 10s" --board stm32f407 --deploy --json
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from tools.db.storage import get_connection
+
+
+# Template library: common intents mapped to FreeRTOS C code templates
+CODE_TEMPLATES = {
+    "blink_led": {
+        "keywords": ["blink", "led", "flash", "toggle"],
+        "template": '''
+#include "FreeRTOS.h"
+#include "task.h"
+#include "hal_gpio.h"
+
+#define LED_PIN {pin}
+
+static void vBlinkTask(void *pvParameters)
+{{
+    hal_gpio_init(LED_PIN, GPIO_MODE_OUTPUT);
+    for (;;)
+    {{
+        hal_gpio_toggle(LED_PIN);
+        vTaskDelay(pdMS_TO_TICKS({delay_ms}));
+    }}
+}}
+
+void app_main(void)
+{{
+    xTaskCreate(vBlinkTask, "blink", configMINIMAL_STACK_SIZE + 128, NULL, 2, NULL);
+    vTaskStartScheduler();
+}}
+''',
+        "default_params": {"pin": "2", "delay_ms": "1000"},
+    },
+    "read_sensor": {
+        "keywords": ["read", "sensor", "temperature", "humidity", "accel"],
+        "template": '''
+#include "FreeRTOS.h"
+#include "task.h"
+#include "hal_i2c.h"
+#include "hal_sensor.h"
+
+static void vSensorTask(void *pvParameters)
+{{
+    hal_i2c_init(I2C_PORT_0, {sda_pin}, {scl_pin}, 400000);
+    sensor_handle_t sensor = hal_sensor_init(SENSOR_{sensor_type});
+
+    for (;;)
+    {{
+        float value = hal_sensor_read(sensor);
+        /* TODO: report via MQTT telemetry */
+        vTaskDelay(pdMS_TO_TICKS({interval_ms}));
+    }}
+}}
+
+void app_main(void)
+{{
+    xTaskCreate(vSensorTask, "sensor", configMINIMAL_STACK_SIZE + 256, NULL, 2, NULL);
+    vTaskStartScheduler();
+}}
+''',
+        "default_params": {"sda_pin": "21", "scl_pin": "22", "sensor_type": "TEMPERATURE", "interval_ms": "1000"},
+    },
+    "mqtt_publish": {
+        "keywords": ["mqtt", "publish", "send", "message", "telemetry"],
+        "template": '''
+#include "FreeRTOS.h"
+#include "task.h"
+#include "sparkpilot_sdk.h"
+
+static void vMqttTask(void *pvParameters)
+{{
+    sparkpilot_init();
+    sparkpilot_mqtt_connect("{broker}", {port});
+
+    for (;;)
+    {{
+        const char *payload = "{message}";
+        sparkpilot_mqtt_publish("{topic}", payload, strlen(payload), {qos});
+        vTaskDelay(pdMS_TO_TICKS({interval_ms}));
+    }}
+}}
+
+void app_main(void)
+{{
+    xTaskCreate(vMqttTask, "mqtt_pub", configMINIMAL_STACK_SIZE + 512, NULL, 3, NULL);
+    vTaskStartScheduler();
+}}
+''',
+        "default_params": {
+            "broker": "mqtt.sparkpilot.local",
+            "port": "1883",
+            "topic": "sparkpilot/telemetry",
+            "message": "hello",
+            "qos": "1",
+            "interval_ms": "10000",
+        },
+    },
+    "wifi_connect": {
+        "keywords": ["wifi", "connect", "network", "internet"],
+        "template": '''
+#include "FreeRTOS.h"
+#include "task.h"
+#include "hal_wifi.h"
+
+static void vWifiTask(void *pvParameters)
+{{
+    wifi_config_t cfg = {{
+        .ssid = "{ssid}",
+        .password = "{password}",
+        .auth_mode = WIFI_AUTH_WPA2_PSK,
+    }};
+    hal_wifi_init(&cfg);
+    hal_wifi_connect();
+
+    /* Block until connected */
+    while (!hal_wifi_is_connected())
+    {{
+        vTaskDelay(pdMS_TO_TICKS(500));
+    }}
+
+    /* WiFi connected — start application tasks */
+    for (;;)
+    {{
+        vTaskDelay(pdMS_TO_TICKS(60000));
+    }}
+}}
+
+void app_main(void)
+{{
+    xTaskCreate(vWifiTask, "wifi", configMINIMAL_STACK_SIZE + 1024, NULL, 4, NULL);
+    vTaskStartScheduler();
+}}
+''',
+        "default_params": {"ssid": "MyNetwork", "password": "********"},
+    },
+}
+
+
+def _now():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _detect_intent(command: str) -> tuple[str, dict]:
+    """Detect user intent from natural language command. Returns (template_key, params)."""
+    command_lower = command.lower()
+
+    # Extract numeric values for timing
+    import re
+    numbers = re.findall(r'(\d+(?:\.\d+)?)\s*(seconds?|s|ms|milliseconds?|minutes?|min|m|hz)', command_lower)
+    delay_ms = None
+    for num_str, unit in numbers:
+        num = float(num_str)
+        if unit.startswith('s') or unit == 'seconds':
+            delay_ms = int(num * 1000)
+        elif unit in ('ms', 'milliseconds'):
+            delay_ms = int(num)
+        elif unit.startswith('min') or unit == 'm':
+            delay_ms = int(num * 60000)
+        elif unit == 'hz':
+            delay_ms = int(1000 / num) if num > 0 else 1000
+
+    best_match = None
+    best_score = 0
+    for key, tpl in CODE_TEMPLATES.items():
+        score = sum(1 for kw in tpl["keywords"] if kw in command_lower)
+        if score > best_score:
+            best_score = score
+            best_match = key
+
+    if not best_match:
+        best_match = "blink_led"  # Safe default for beginners
+
+    params = dict(CODE_TEMPLATES[best_match]["default_params"])
+    if delay_ms is not None:
+        if "delay_ms" in params:
+            params["delay_ms"] = str(delay_ms)
+        elif "interval_ms" in params:
+            params["interval_ms"] = str(delay_ms)
+
+    return best_match, params
+
+
+def generate_code(command: str, board: str = "simulator", params: dict | None = None) -> dict:
+    """Generate FreeRTOS C code from natural language command."""
+    intent, detected_params = _detect_intent(command)
+    if params:
+        detected_params.update(params)
+
+    template_info = CODE_TEMPLATES[intent]
+    code = template_info["template"].format(**detected_params).strip()
+
+    cmd_id = str(uuid.uuid4())[:8]
+    record = {
+        "id": f"nl-{cmd_id}",
+        "raw_input": command,
+        "parsed_intent": json.dumps({"intent": intent, "params": detected_params}),
+        "generated_code": code,
+        "target_board": board,
+        "status": "generated",
+    }
+
+    # Store in DB
+    conn = get_connection()
+    try:
+        conn.execute(
+            "INSERT INTO nl_commands (id, user_id, raw_input, parsed_intent, "
+            "generated_code, target_board, status) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (record["id"], "cli", command, record["parsed_intent"],
+             code, board, "generated"),
+        )
+        conn.commit()
+    except Exception:
+        pass
+    finally:
+        conn.close()
+
+    return {
+        "status": "success",
+        "command_id": record["id"],
+        "intent": intent,
+        "params": detected_params,
+        "board": board,
+        "code": code,
+        "next_steps": [
+            f"Compile: python tools/embedded/cmake_generator.py --project-id proj --board {board}",
+            f"Deploy: python tools/fleet/ota_manager.py --firmware-id <id> --device-id <id>",
+            "Or load in simulator: python tools/simulator/sim_runner.py --code <file>",
+        ],
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Natural Language to Firmware")
+    parser.add_argument("--command", required=True, help="Natural language command")
+    parser.add_argument("--board", default="simulator", help="Target board (default: simulator)")
+    parser.add_argument("--json", action="store_true", help="JSON output")
+    parser.add_argument("--deploy", action="store_true", help="Auto-deploy after generation")
+    args = parser.parse_args()
+
+    result = generate_code(args.command, args.board)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"Intent: {result['intent']}")
+        print(f"Board: {result['board']}")
+        print(f"Command ID: {result['command_id']}")
+        print("\n--- Generated Code ---")
+        print(result["code"])
+        print("\n--- Next Steps ---")
+        for step in result["next_steps"]:
+            print(f"  {step}")
+
+
+if __name__ == "__main__":
+    main()

tools/events/__init__.py

@@ -0,0 +1 @@
+# CUI // SP-CTI

tools/events/event_bus.py

@@ -0,0 +1,199 @@
+# CUI // SP-CTI
+"""Lightweight in-process event bus for ICDEV domain events.
+
+Provides publish/subscribe decoupling between tools, agents, and the
+orchestration layer.  Events are synchronous by default (handler runs
+in the publisher's thread) with an optional async fire-and-forget mode.
+
+Design decisions:
+  - No external dependencies (stdlib only).
+  - Thread-safe registration and dispatch.
+  - Handlers are plain callables ``(event: DomainEvent) -> None``.
+  - Events are frozen dataclass instances (immutable after creation).
+  - Supports wildcard ``*`` subscriptions for audit / telemetry sinks.
+
+Usage::
+
+    from tools.events.event_bus import bus, DomainEvent
+
+    # Subscribe
+    bus.subscribe("compliance.gate_passed", my_handler)
+    bus.subscribe("*", audit_logger)          # catch-all
+
+    # Publish
+    bus.publish(DomainEvent(
+        topic="compliance.gate_passed",
+        payload={"gate": "stig_check", "result": "pass"},
+    ))
+
+Classification: CUI // SP-CTI
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+logger = logging.getLogger("icdev.events.bus")
+
+# ---------------------------------------------------------------------------
+# Domain event
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class DomainEvent:
+    """Immutable domain event."""
+
+    topic: str
+    payload: Dict[str, Any] = field(default_factory=dict)
+    event_id: str = field(default_factory=lambda: f"evt-{uuid.uuid4().hex[:12]}")
+    timestamp: float = field(default_factory=time.time)
+    source: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "event_id": self.event_id,
+            "topic": self.topic,
+            "payload": self.payload,
+            "timestamp": self.timestamp,
+            "source": self.source,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Well-known event topics (D-ARCH-7)
+# ---------------------------------------------------------------------------
+
+# Agent lifecycle
+AGENT_STARTED = "agent.started"
+AGENT_STOPPED = "agent.stopped"
+AGENT_HEALTH_CHANGED = "agent.health_changed"
+
+# Compliance
+COMPLIANCE_GATE_PASSED = "compliance.gate_passed"
+COMPLIANCE_GATE_FAILED = "compliance.gate_failed"
+COMPLIANCE_EVIDENCE_COLLECTED = "compliance.evidence_collected"
+
+# Security
+SECURITY_THREAT_DETECTED = "security.threat_detected"
+SECURITY_SCAN_COMPLETED = "security.scan_completed"
+
+# LLM
+LLM_FALLBACK_TRIGGERED = "llm.fallback_triggered"
+LLM_CIRCUIT_OPENED = "llm.circuit_opened"
+
+# Build / deploy
+BUILD_COMPLETED = "build.completed"
+DEPLOY_STARTED = "deploy.started"
+DEPLOY_COMPLETED = "deploy.completed"
+
+# DLQ
+TASK_SENT_TO_DLQ = "task.sent_to_dlq"
+
+
+# ---------------------------------------------------------------------------
+# Handler type
+# ---------------------------------------------------------------------------
+
+EventHandler = Callable[[DomainEvent], None]
+
+
+# ---------------------------------------------------------------------------
+# Event bus
+# ---------------------------------------------------------------------------
+
+class EventBus:
+    """In-process publish/subscribe event bus.
+
+    Thread-safe.  Handlers registered for a specific topic receive only
+    matching events.  Handlers registered for ``"*"`` receive all events.
+    """
+
+    def __init__(self) -> None:
+        self._handlers: Dict[str, List[EventHandler]] = {}
+        self._lock = threading.Lock()
+        self._event_log: List[Dict[str, Any]] = []
+        self._log_limit = 500  # rolling buffer
+
+    # -- Subscribe / unsubscribe --------------------------------------------
+
+    def subscribe(self, topic: str, handler: EventHandler) -> None:
+        """Register *handler* for *topic* (use ``"*"`` for catch-all)."""
+        with self._lock:
+            self._handlers.setdefault(topic, []).append(handler)
+        logger.debug("Subscribed %s to topic '%s'", handler, topic)
+
+    def unsubscribe(self, topic: str, handler: EventHandler) -> None:
+        """Remove a previously registered handler."""
+        with self._lock:
+            handlers = self._handlers.get(topic, [])
+            try:
+                handlers.remove(handler)
+            except ValueError:
+                pass
+
+    # -- Publish ------------------------------------------------------------
+
+    def publish(self, event: DomainEvent) -> None:
+        """Dispatch *event* to all matching handlers (synchronous).
+
+        Handlers are called in registration order.  Exceptions in one
+        handler are logged but do not prevent subsequent handlers from
+        running.
+        """
+        with self._lock:
+            # Topic-specific + wildcard
+            handlers = list(self._handlers.get(event.topic, []))
+            handlers += list(self._handlers.get("*", []))
+
+        for handler in handlers:
+            try:
+                handler(event)
+            except Exception as exc:
+                logger.error(
+                    "Handler %s failed for event %s: %s",
+                    handler, event.event_id, exc,
+                )
+
+        # Rolling log for diagnostics
+        self._append_log(event)
+
+    def _append_log(self, event: DomainEvent) -> None:
+        self._event_log.append(event.to_dict())
+        if len(self._event_log) > self._log_limit:
+            self._event_log = self._event_log[-self._log_limit:]
+
+    # -- Introspection ------------------------------------------------------
+
+    def recent_events(self, limit: int = 50, topic: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Return recent events (newest first), optionally filtered by topic."""
+        events = self._event_log[::-1]
+        if topic:
+            events = [e for e in events if e["topic"] == topic]
+        return events[:limit]
+
+    def registered_topics(self) -> List[str]:
+        """List all topics with at least one handler."""
+        with self._lock:
+            return [t for t, h in self._handlers.items() if h]
+
+    def handler_count(self, topic: str) -> int:
+        with self._lock:
+            return len(self._handlers.get(topic, []))
+
+    def reset(self) -> None:
+        """Clear all handlers and event log (testing only)."""
+        with self._lock:
+            self._handlers.clear()
+            self._event_log.clear()
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton
+# ---------------------------------------------------------------------------
+
+bus = EventBus()