Initial Comms Framework

.github/workflows/build.yml

@@ -0,0 +1,122 @@
+name: Build
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - 'v*'
+
+jobs:
+  console:
+    name: Build Console
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v6.0.2
+
+      - uses: oven-sh/setup-bun@3d267786b128fe76c2f16a390aa2448b815359f3 # v2.1.2
+
+      - name: Install dependencies
+        working-directory: console
+        run: bun install --frozen-lockfile
+
+      - name: Build console
+        working-directory: console
+        run: bun run build
+
+      - name: Upload console artifacts
+        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.5.0
+        with:
+          name: lucid-console
+          path: console/dist/
+          if-no-files-found: error
+
+  build:
+    name: Build (${{ matrix.target }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            os: ubuntu-latest
+          - target: x86_64-unknown-linux-musl
+            os: ubuntu-latest
+          - target: aarch64-unknown-linux-gnu
+            os: ubuntu-latest
+          - target: aarch64-unknown-linux-musl
+            os: ubuntu-latest
+          - target: x86_64-apple-darwin
+            os: macos-latest
+          - target: aarch64-apple-darwin
+            os: macos-latest
+
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v6.0.2
+
+      - uses: dtolnay/rust-toolchain@7b1c307e0dcbda6122208f10795a713336a9b35a # v1
+        with:
+          toolchain: stable
+          targets: ${{ matrix.target }}
+
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2.8.2
+        with:
+          key: ${{ matrix.target }}
+
+      - name: Install cross-compilation tools
+        if: runner.os == 'Linux' && contains(matrix.target, 'musl')
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y musl-tools
+
+      - name: Install cross-compilation tools (aarch64)
+        if: runner.os == 'Linux' && contains(matrix.target, 'aarch64')
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc-aarch64-linux-gnu
+
+      - name: Build
+        run: cargo build --release --target ${{ matrix.target }} --workspace
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.5.0
+        with:
+          name: lucid-${{ matrix.target }}
+          path: |
+            target/${{ matrix.target }}/release/lucid-api
+            target/${{ matrix.target }}/release/lucid-agent
+          if-no-files-found: error
+
+  release:
+    name: Create Release
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: [build, console]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v6.0.2
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+
+      - name: Create archives
+        run: |
+          for dir in lucid-*; do
+            if [ "$dir" = "lucid-console" ]; then
+              cd "$dir"
+              tar czf "../lucid-console.tar.gz" .
+              cd ..
+            else
+              target="${dir#lucid-}"
+              cd "$dir"
+              tar czf "../${dir}.tar.gz" *
+              cd ..
+            fi
+          done
+
+      - name: Create release
+        uses: softprops/action-gh-release@e7a8f85e1c67a31e6ed99a94b41bd0b71bbee6b8 # v2.2.0
+        with:
+          draft: true
+          files: lucid-*.tar.gz
+          generate_release_notes: true

.github/workflows/pr-console.yml

@@ -0,0 +1,65 @@
+name: PR Validation (Console)
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'console/**'
+      - '.github/workflows/pr-console.yml'
+  merge_group:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: console
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v6.0.2
+
+      - uses: oven-sh/setup-bun@3d267786b128fe76c2f16a390aa2448b815359f3 # v2.1.2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run tests
+        run: bun run test
+
+  check:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: console
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v6.0.2
+
+      - uses: oven-sh/setup-bun@3d267786b128fe76c2f16a390aa2448b815359f3 # v2.1.2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run biome check
+        run: bun check
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: console
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v6.0.2
+
+      - uses: oven-sh/setup-bun@3d267786b128fe76c2f16a390aa2448b815359f3 # v2.1.2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build

.github/workflows/pr-rust.yml

@@ -0,0 +1,99 @@
+name: PR Validation (Rust)
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'agent/**'
+      - 'api/**'
+      - 'common/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - '.github/workflows/pr-rust.yml'
+  merge_group:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v6.0.2
+
+      - uses: dtolnay/rust-toolchain@7b1c307e0dcbda6122208f10795a713336a9b35a # v1
+        with:
+          toolchain: stable
+          components: rustfmt, clippy
+
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2.8.2
+
+      - name: Run tests
+        run: cargo test --workspace --all-features
+
+  fmt:
+    name: Formatting
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v6.0.2
+
+      - uses: dtolnay/rust-toolchain@7b1c307e0dcbda6122208f10795a713336a9b35a # v1
+        with:
+          toolchain: stable
+          components: rustfmt
+
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+
+  clippy:
+    name: Clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v6.0.2
+
+      - uses: dtolnay/rust-toolchain@7b1c307e0dcbda6122208f10795a713336a9b35a # v1
+        with:
+          toolchain: stable
+          components: clippy
+
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2.8.2
+
+      - name: Run clippy
+        run: cargo clippy --workspace --all-features -- -D warnings
+
+  openapi:
+    name: OpenAPI Schema
+    runs-on: ubuntu-latest
+    services:
+      mongodb:
+        image: mongodb/mongodb-community-server:8.0-ubi8
+        ports: [27017:27017]
+    env:
+      LUCID_API_DB_URL: mongodb://localhost:27017/lucid
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v6.0.2
+
+      - uses: dtolnay/rust-toolchain@7b1c307e0dcbda6122208f10795a713336a9b35a # v1
+        with:
+          toolchain: stable
+
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2.8.2
+
+      - name: Generate signing key
+        run: openssl genpkey -algorithm ED25519 -out signing_key.pem
+
+      - name: Generate OpenAPI schema
+        env:
+          LUCID_API_SIGNING_KEY_FILE: signing_key.pem
+        run: cargo run --bin lucid-api -- --dump-openapi > /tmp/openapi.json
+
+      - name: Check schema is up to date
+        run: |
+          if ! diff -q api/openapi.json /tmp/openapi.json; then
+            echo "❌ OpenAPI schema is out of date"
+            echo "Run: cargo run --bin lucid-api -- --dump-openapi > api/openapi.json"
+            exit 1
+          fi
+          echo "✅ OpenAPI schema is up to date"

.gitignore

@@ -158,3 +158,6 @@ Cargo.lock
 
 # Antora Docs
 build/
+
+mise.local.toml
+config/local

.opencode/skills/db-model-impl/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: db-model-impl
+description: Finish implementing the logic for a database model written by a developer.
+license: Apache-2.0
+compatibility: opencode
+metadata:
+  audience: maintainers
+  workflow: github
+---
+
+## What I do
+
+- Create a storage filter struct for the created model
+- Create a `Store` trait for the model (i.e. `HostStore`)
+- Implement the new `Store` trait for all `Storage` trait implementations
+- Add any relevant permissions to the `Permissions` enum in `lucid-common`
+
+## When to use me
+
+Use this when you are tasked with finishing implementation of a database model,
+or when writing a _new_ database model.

AGENTS.md

@@ -0,0 +1,22 @@
+# Lucid Agent Guidelines
+
+Be sure to read the [README](./README.adoc) for information on what Lucid
+actually is and aims to enable.
+
+Lucid is built from three key components:
+
+- `api/`, the API service that everything interfaces with
+- `agent/`, the host agent responsible for collecting host telemetry
+- `console/`, the web UI used by administrators to interface with the system
+
+## Coding Guidelines
+
+### Rust
+
+- All dependencies must be declared in the root `Cargo.toml`, not locally to
+  individual crates.
+
+- After editing any Rust code, you **must** run `cargo fmt` on the changed
+  files.
+
+- Always write unit tests for logic, write integration tests where relevant.

CONTRIBUTING.adoc

@@ -50,6 +50,15 @@ If you would like to contribute to Lucid, but are not exactly sure what to work
 on, you can find a number of open issues that are awaiting contributions in
 https://github.com/roostmoe/lucid/issues[Issues].
 
+=== Updating the API documentation
+
+When updating the API, ensure you have updated the OpenAPI specification.
+
+[source,bash]
+----
+$ cargo run -p lucid-api -- --dump-openapi > api/openapi.json
+----
+
 == Reporting Vulnerabilities
 
 If you have found a security vulnerability in Lucid, please follow the