feat: Sprint 0.1 — monorepo foundation with VM, wire protocol, CI/CD

.github/workflows/esp32-build.yml

@@ -0,0 +1,63 @@
+name: ESP32 Build
+
+on:
+  push:
+    paths:
+      - 'firmware/**'
+      - 'shared/**'
+      - 'CMakeLists.txt'
+  pull_request:
+    paths:
+      - 'firmware/**'
+      - 'shared/**'
+      - 'CMakeLists.txt'
+
+jobs:
+  build-firmware:
+    name: ESP32-S3 Firmware Build
+    runs-on: ubuntu-latest
+    container:
+      image: espressif/idf:v5.3
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build firmware
+        working-directory: firmware
+        run: |
+          . $IDF_PATH/export.sh
+          idf.py set-target esp32s3
+          idf.py build
+        shell: bash
+
+      - name: Check binary size
+        working-directory: firmware
+        run: |
+          SIZE=$(stat -c%s build/nexus_firmware.bin 2>/dev/null || echo "0")
+          echo "Binary size: $SIZE bytes"
+          if [ "$SIZE" -gt 1048576 ]; then
+            echo "ERROR: Binary exceeds 1MB limit"
+            exit 1
+          fi
+
+      - name: Archive build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: esp32-firmware
+          path: |
+            firmware/build/nexus_firmware.bin
+            firmware/build/nexus_firmware.elf
+          retention-days: 7
+
+  lint-c:
+    name: C Code Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install clang-format
+        run: sudo apt-get install -y clang-format
+
+      - name: Check formatting
+        run: |
+          find firmware/ shared/ -name '*.c' -o -name '*.h' | \
+            xargs clang-format --dry-run --Werror

.github/workflows/esp32-test.yml

@@ -0,0 +1,54 @@
+name: ESP32 Unit Tests
+
+on:
+  push:
+    paths:
+      - 'firmware/**'
+      - 'shared/**'
+      - 'tests/unit/firmware/**'
+      - 'CMakeLists.txt'
+  pull_request:
+    paths:
+      - 'firmware/**'
+      - 'shared/**'
+      - 'tests/unit/firmware/**'
+      - 'CMakeLists.txt'
+
+jobs:
+  host-tests:
+    name: VM Unit Tests (Host)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake build-essential
+
+      - name: Setup Unity test framework
+        run: |
+          mkdir -p third_party/unity/src
+          if [ ! -f third_party/unity/src/unity.c ]; then
+            echo "Unity framework not vendored — downloading"
+            curl -sL https://raw.githubusercontent.com/ThrowTheSwitch/Unity/master/src/unity.c \
+              -o third_party/unity/src/unity.c
+            curl -sL https://raw.githubusercontent.com/ThrowTheSwitch/Unity/master/src/unity.h \
+              -o third_party/unity/src/unity.h
+            curl -sL https://raw.githubusercontent.com/ThrowTheSwitch/Unity/master/src/unity_internals.h \
+              -o third_party/unity/src/unity_internals.h
+          fi
+
+      - name: Build host tests
+        run: |
+          mkdir -p build
+          cd build
+          cmake -DNEXUS_HOST_TEST=ON ..
+          make -j$(nproc)
+
+      - name: Run tests
+        run: |
+          cd build
+          ctest --output-on-failure -j$(nproc)

.github/workflows/jetson-build.yml

@@ -0,0 +1,44 @@
+name: Jetson Build & Lint
+
+on:
+  push:
+    paths:
+      - 'jetson/**'
+      - 'shared/bytecode/opcodes.py'
+  pull_request:
+    paths:
+      - 'jetson/**'
+      - 'shared/bytecode/opcodes.py'
+
+jobs:
+  lint:
+    name: Python Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          pip install ruff mypy
+          pip install -r jetson/requirements.txt || true
+
+      - name: Ruff check
+        run: ruff check jetson/ shared/bytecode/opcodes.py
+
+      - name: Ruff format check
+        run: ruff format --check jetson/ shared/bytecode/opcodes.py
+
+      - name: Mypy type check
+        run: mypy jetson/ shared/bytecode/opcodes.py --ignore-missing-imports
+
+      - name: Import validation
+        run: |
+          python -c "import jetson.nexus_sdk; print(f'SDK version: {jetson.nexus_sdk.__version__}')"
+          python -c "from shared.bytecode.opcodes import Opcode, Instruction; print(f'Opcodes: {len(Opcode)}')"
+        env:
+          PYTHONPATH: .

.github/workflows/jetson-test.yml

@@ -0,0 +1,37 @@
+name: Jetson Tests
+
+on:
+  push:
+    paths:
+      - 'jetson/**'
+      - 'shared/**'
+      - 'tests/unit/jetson/**'
+  pull_request:
+    paths:
+      - 'jetson/**'
+      - 'shared/**'
+      - 'tests/unit/jetson/**'
+
+jobs:
+  test:
+    name: Pytest Suite
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          pip install pytest pytest-cov numpy scipy
+          pip install -r jetson/requirements.txt || true
+
+      - name: Run tests
+        run: |
+          pytest tests/unit/jetson/ -v --cov=jetson --cov=shared \
+            --cov-report=term-missing --cov-fail-under=80
+        env:
+          PYTHONPATH: .

.gitignore

@@ -22,3 +22,24 @@ coredump
 
 # Large binary caches (keep archives/)
 *.zip~
+
+# Build artifacts
+build/
+firmware/build/
+firmware/sdkconfig
+firmware/sdkconfig.old
+
+# ESP-IDF
+firmware/managed_components/
+
+# Python
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+dist/
+
+# Environment
+.env
+*.env.local

CMakeLists.txt

@@ -0,0 +1,61 @@
+# NEXUS Distributed Intelligence Platform — Top-Level CMakeLists.txt
+# This file orchestrates builds for both ESP32-S3 firmware and host-based tests.
+#
+# Usage:
+#   ESP32 firmware build: cd firmware && idf.py build
+#   Host unit tests:      mkdir build && cd build && cmake -DNEXUS_HOST_TEST=ON .. && make && ctest
+
+cmake_minimum_required(VERSION 3.16)
+project(nexus VERSION 0.1.0 LANGUAGES C CXX)
+
+option(NEXUS_HOST_TEST "Build host-side unit tests (Unity framework)" OFF)
+
+if(NEXUS_HOST_TEST)
+    enable_testing()
+
+    set(CMAKE_C_STANDARD 11)
+    set(CMAKE_C_STANDARD_REQUIRED ON)
+    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wall -Wextra -Werror -Wno-unused-parameter")
+
+    # Unity test framework (vendored in third_party/)
+    add_library(unity STATIC third_party/unity/src/unity.c)
+    target_include_directories(unity PUBLIC third_party/unity/src)
+
+    # VM library (compiled for host)
+    add_library(nexus_vm STATIC
+        firmware/nexus_vm/vm_core.c
+        firmware/nexus_vm/vm_opcodes.c
+        firmware/nexus_vm/vm_validate.c
+        firmware/nexus_vm/vm_syscalls.c
+    )
+    target_include_directories(nexus_vm PUBLIC
+        firmware/nexus_vm/include
+        shared/bytecode
+    )
+
+    # Wire protocol library (compiled for host)
+    add_library(nexus_wire STATIC
+        firmware/wire_protocol/cobs.c
+        firmware/wire_protocol/crc16.c
+    )
+    target_include_directories(nexus_wire PUBLIC
+        firmware/wire_protocol
+    )
+
+    # Unit tests
+    file(GLOB VM_TEST_SOURCES tests/unit/firmware/test_vm_*.c)
+    foreach(test_src ${VM_TEST_SOURCES})
+        get_filename_component(test_name ${test_src} NAME_WE)
+        add_executable(${test_name} ${test_src})
+        target_link_libraries(${test_name} nexus_vm unity m)
+        add_test(NAME ${test_name} COMMAND ${test_name})
+    endforeach()
+
+    file(GLOB WIRE_TEST_SOURCES tests/unit/firmware/test_cobs*.c tests/unit/firmware/test_crc*.c)
+    foreach(test_src ${WIRE_TEST_SOURCES})
+        get_filename_component(test_name ${test_src} NAME_WE)
+        add_executable(${test_name} ${test_src})
+        target_link_libraries(${test_name} nexus_wire unity m)
+        add_test(NAME ${test_name} COMMAND ${test_name})
+    endforeach()
+endif()

firmware/CMakeLists.txt

@@ -0,0 +1,15 @@
+# NEXUS ESP32-S3 Firmware — ESP-IDF Top-Level Project CMakeLists.txt
+# Build with: idf.py set-target esp32s3 && idf.py build
+
+cmake_minimum_required(VERSION 3.16)
+
+# ESP-IDF component directories
+set(EXTRA_COMPONENT_DIRS
+    "${CMAKE_CURRENT_SOURCE_DIR}/nexus_vm"
+    "${CMAKE_CURRENT_SOURCE_DIR}/wire_protocol"
+    "${CMAKE_CURRENT_SOURCE_DIR}/safety"
+    "${CMAKE_CURRENT_SOURCE_DIR}/drivers"
+)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(nexus_firmware)

firmware/drivers/CMakeLists.txt

@@ -0,0 +1,4 @@
+idf_component_register(
+    SRCS "io_poll.c" "sensor_bus.c" "actuator_drv.c"
+    INCLUDE_DIRS "."
+)

firmware/drivers/actuator_drv.c

@@ -0,0 +1,7 @@
+/**
+ * NEXUS Drivers — Actuator Output Driver
+ *
+ * Sprint 0.2+ stub. Spec: specs/firmware/io_driver_interface.h
+ */
+
+/* Placeholder — implemented in Sprint 0.2 */

firmware/drivers/io_poll.c

@@ -0,0 +1,7 @@
+/**
+ * NEXUS Drivers — Polled I/O Acquisition Task
+ *
+ * Sprint 0.2+ stub. Spec: specs/firmware/io_driver_interface.h
+ */
+
+/* Placeholder — implemented in Sprint 0.2 */

firmware/drivers/sensor_bus.c

@@ -0,0 +1,7 @@
+/**
+ * NEXUS Drivers — I2C/SPI Sensor Bus Drivers
+ *
+ * Sprint 0.2+ stub. Spec: specs/firmware/io_driver_interface.h
+ */
+
+/* Placeholder — implemented in Sprint 0.2 */

firmware/main/CMakeLists.txt

@@ -0,0 +1,5 @@
+idf_component_register(
+    SRCS "app_main.c"
+    INCLUDE_DIRS "."
+    REQUIRES nexus_vm wire_protocol safety drivers
+)