From 1f568d63f5dc87cc6d029cb9c06e42b6cf4b74fe Mon Sep 17 00:00:00 2001 From: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com> Date: Fri, 20 Nov 2026 14:44:59 +0100 Subject: [PATCH 1/2] docs: replace project-context.md with a tracked CLAUDE.md Nothing loads project-context.md since the ai-templates generator is gone. Keep the repo knowledge that is still true as a tracked CLAUDE.md, which Claude Code loads by default, and drop what the shared team setup already covers. Remove the generator entries from .gitignore. Bump the version to 0.29.2. Signed-off-by: Jan Zachmann 50990105+JanZachmann@users.noreply.github.com --- .gitignore | 4 --- CLAUDE.md | 49 ++++++++++++++++++++++++++++ Cargo.lock | 2 +- Cargo.toml | 2 +- project-context.md | 81 ---------------------------------------------- 5 files changed, 51 insertions(+), 87 deletions(-) create mode 100644 CLAUDE.md delete mode 100644 project-context.md diff --git a/.gitignore b/.gitignore index 7462742..1045c65 100644 --- a/.gitignore +++ b/.gitignore @@ -7,7 +7,3 @@ *.xml .vscode/launch.json docker-run.sh -setup-ai.sh -.user-context.md -CLAUDE.md -GEMINI.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..631b730 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,49 @@ +# omnect-cli + +Command-line tool for developer hosts. It changes omnect OS firmware images +(device identity, certificates, config files, docker images in the image) +and works with devices in the field (SSH tunnel over a bastion host) and +Azure Device Update (create import manifest, import, remove). + +## Structure + +- `src/cli.rs`: clap definitions of all commands; `src/lib.rs`: `run()` + dispatches them to the handlers. +- `src/auth.rs`, `src/config.rs`: OAuth2 PKCE login against Keycloak with a + local redirect server; the refresh token goes to the system keyring. +- `src/device_update/`: Device Update REST client, token and blob SAS code. +- `src/file/`: image operations. `functions.rs` reads a partition out of + the image, changes it with e2tools or mtools and writes back only the + changed blocks. `partition.rs` reads GPT and MBR tables. +- `src/file/sparse.rs`, `bmap.rs`, `output.rs`: keep holes of sparse + images, check and write the bmap, choose the output name and check that + the output image and bmap do not overwrite other files. +- `src/file/signal.rs`: `RegisteredTempDir` is also removed when SIGINT, + SIGTERM or SIGHUP stop the process. +- `src/validators/`: checks for identity config, `du-config.json` and SSH + keys. +- `conf/`: config templates. Its `.gitignore` tracks only `*.template`; + configs made from them are never committed. + +## Constraints + +- Partition numbers depend on the table type: `factory` and `cert` are 4 + and 5 on GPT, 5 and 6 on MBR. The mapping is in `get_partition_info()` in + `src/file/functions.rs`. +- The binary calls external tools: `e2cp`, `e2mkdir`, `mcopy`, `mmd`, + `ssh-keygen` and `docker`. The distroless image in `Dockerfile` contains + only the executables in its explicit copy list, so a new external tool + must be added there too. +- `CONTAINERIZED=true` (set in the docker image) changes behaviour: the + OAuth redirect server binds `0.0.0.0:4000` instead of `127.0.0.1:4000` + and `[::1]:4000`, `docker inject` and custom SSH config dirs are refused. +- Errors use `anyhow`; this is an application, not a library. + +## Commands + +- Build: `cargo build` (needs `libmagic-dev` on the host) +- Test: `cargo test`. Integration tests need e2tools and mtools on the + host and use temp dirs under `/tmp/omnect-cli-integration-tests/`. +- Debian package: `cargo deb` (writes to `target/debian/`) +- Docker image: `./build-image.sh`. It takes the version from `Cargo.toml` + and installs the `.deb` from `target/debian/`, so run `cargo deb` first. diff --git a/Cargo.lock b/Cargo.lock index c12947b..3b38821 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1748,7 +1748,7 @@ dependencies = [ [[package]] name = "omnect-cli" -version = "0.29.1" +version = "0.29.2" dependencies = [ "actix-web", "anyhow", diff --git a/Cargo.toml b/Cargo.toml index e138ec1..f27c292 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -7,7 +7,7 @@ license = "MIT OR Apache-2.0" name = "omnect-cli" readme = "README.md" repository = "https://github.com/omnect/omnect-cli" -version = "0.29.1" +version = "0.29.2" [dependencies] actix-web = { version = "4.17", default-features = false, features = ["macros"] } diff --git a/project-context.md b/project-context.md deleted file mode 100644 index b683176..0000000 --- a/project-context.md +++ /dev/null @@ -1,81 +0,0 @@ - - -# Project Context - -## 1. Role & Responsibility - -- **Role:** CLI tool to configure omnect-os firmware images (partition manipulation, identity injection, Docker container embedding) and communicate with omnect-os devices (SSH tunneling, Azure Device Update import/removal). -- **Runtime Target:** Developer workstation (native or Docker container via distroless image; `CONTAINERIZED` env var toggles container-aware behavior). - -## 2. Architecture & Tech Stack - -- **Language / Runtime:** Rust (edition 2024), async via Tokio + Actix-web -- **Key Frameworks:** clap 4.5 (derive) for CLI, actix-web for local OAuth2 redirect server, reqwest for HTTP -- **Notable Dependencies:** - - Azure SDK from **omnect fork** (`omnect/azure-sdk-for-rust`) — blocked on upstream PR #1636 - - `omnect-crypto` 0.4.0 for device certificate creation - - `gptman`/`mbrman` for partition table parsing (GPT+MBR) - - `filemagic` for compression auto-detection - - `keyring` for system credential storage (OAuth refresh tokens) - - `e2tools` + `mtools` (external binaries) for ext4/FAT32 partition file operations - - `anyhow` for error handling (CLI tool, ergonomics over type precision) - -## 3. Key Entry Points & Files - -- `src/main.rs` — binary entry point; sets up env_logger, calls `omnect_cli::run()` -- `src/lib.rs` — command dispatch hub; `run()` parses CLI args and delegates to handlers -- `src/cli.rs` — clap `Parser`/`Subcommand` definitions for all commands -- `src/auth.rs` — OAuth2 PKCE flow against Keycloak (local redirect server on :4000) -- `src/config.rs` — Keycloak provider config, backend URL constants -- `src/ssh.rs` — SSH tunnel creation via bastion host, ed25519 key generation -- `src/device_update.rs` — Azure Device Update import manifest creation, import/remove -- `src/docker.rs` — `docker pull --platform` + `docker save` for multi-arch images -- `src/image.rs` — firmware image architecture detection (ARM32/ARM64/x86_64) -- `src/file/mod.rs` — high-level image operations: identity config, certs, hostname patching -- `src/file/functions.rs` — sparse partition read, modify via e2cp/mcopy, write back of changed blocks only -- `src/file/bmap.rs` — input bmap lookup and checksum check; writes the output bmap: input ranges (or the whole image) plus data blocks -- `src/file/output.rs` — output image name, conflict checks, staged write and commit of the output image and bmap -- `src/file/sparse.rs` — data/hole ranges via `SEEK_DATA`/`SEEK_HOLE`, sparse range copy -- `src/file/signal.rs` — `RegisteredTempDir`: a temp dir that SIGINT/SIGTERM/SIGHUP (unless ignored) also removes -- `src/file/partition.rs` — GPT/MBR partition table parsing -- `src/file/compression.rs` — xz/bzip2/gzip compress/decompress with auto-detection -- `src/validators/` — validation for identity config (TOML), device-update config (JSON), SSH keys -- `conf/*.template` — 11 config templates (identity, device-update, WiFi) - -## 4. Repository-Specific Constraints - -- External tools `e2cp`, `e2mkdir`, `mcopy`, `mmd`, `ssh-keygen`, `fdisk` must be available at runtime (Dockerfile copies them explicitly). -- Partition enum maps partition names to numbers differently for GPT vs MBR — see `file/functions.rs`. -- OAuth2 callback binds to `127.0.0.1:4000` and `[::1]:4000`; container mode overrides to `0.0.0.0`. -- `conf/` directory uses `.gitignore` to track only `*.template` files — actual configs are generated, never committed. -- Azure SDK crates use a **fork** (`omnect/azure-sdk-for-rust`) with `default-features = false`. Do not switch to upstream until PR #1636 is merged. - -## 5. Local Dev Scripts - -- **Build:** `cargo build` / `cargo build --release` -- **Run Tests:** `cargo test` (unit + integration; integration tests create temp dirs under `/tmp/omnect-cli-integration-tests/`) -- **Lint:** `cargo clippy` / `cargo fmt --check` -- **Debian Package:** `cargo deb` (requires `cargo-deb`; output in `target/debian/`) -- **Docker Image:** `./build-image.sh` (extracts version from Cargo.toml, builds distroless image) - -## 6. Global Rule Overrides - -- Uses `anyhow` instead of custom error types — this is a CLI tool where error ergonomics outweigh type precision. From 97e2b842076672debfab70761e23b26236e25b25 Mon Sep 17 00:00:00 2001 From: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com> Date: Fri, 20 Nov 2026 15:13:22 +0100 Subject: [PATCH 2/2] docs(claude): fix CLAUDE.md claims found in review Signed-off-by: Jan Zachmann 50990105+JanZachmann@users.noreply.github.com --- CLAUDE.md | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 631b730..5a0b591 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,6 +12,9 @@ Azure Device Update (create import manifest, import, remove). - `src/auth.rs`, `src/config.rs`: OAuth2 PKCE login against Keycloak with a local redirect server; the refresh token goes to the system keyring. - `src/device_update/`: Device Update REST client, token and blob SAS code. +- `src/ssh.rs`: SSH tunnel over the bastion host, key pair creation. + `src/image.rs`: architecture of the firmware image; `src/docker.rs`: + pull and save docker images for it. - `src/file/`: image operations. `functions.rs` reads a partition out of the image, changes it with e2tools or mtools and writes back only the changed blocks. `partition.rs` reads GPT and MBR tables. @@ -31,19 +34,25 @@ Azure Device Update (create import manifest, import, remove). and 5 on GPT, 5 and 6 on MBR. The mapping is in `get_partition_info()` in `src/file/functions.rs`. - The binary calls external tools: `e2cp`, `e2mkdir`, `mcopy`, `mmd`, - `ssh-keygen` and `docker`. The distroless image in `Dockerfile` contains - only the executables in its explicit copy list, so a new external tool - must be added there too. -- `CONTAINERIZED=true` (set in the docker image) changes behaviour: the - OAuth redirect server binds `0.0.0.0:4000` instead of `127.0.0.1:4000` - and `[::1]:4000`, `docker inject` and custom SSH config dirs are refused. -- Errors use `anyhow`; this is an application, not a library. + `ssh-keygen` and, on the host only, `docker`. The distroless image in + `Dockerfile` contains only the executables in its explicit copy list. A + new tool goes into the `apt-get install` list and the copy list of + `Dockerfile`, and into `depends` of `[package.metadata.deb]` in + `Cargo.toml`. +- `CONTAINERIZED=true` or `1` (set in the docker image) changes behaviour: + the OAuth redirect server binds `0.0.0.0:4000` instead of + `127.0.0.1:4000` and `[::1]:4000`; `docker inject` and + `ssh set-connection --dir` are refused. +- Errors use `anyhow`; the library target exists only for the binary and + the tests. ## Commands - Build: `cargo build` (needs `libmagic-dev` on the host) -- Test: `cargo test`. Integration tests need e2tools and mtools on the - host and use temp dirs under `/tmp/omnect-cli-integration-tests/`. -- Debian package: `cargo deb` (writes to `target/debian/`) +- Test: `cargo test`. Integration tests need e2tools, mtools and + `ssh-keygen` on the host and use temp dirs under + `/tmp/omnect-cli-integration-tests/`. +- Debian package: `cargo deb` (needs `cargo install cargo-deb`; writes to + `target/debian/`) - Docker image: `./build-image.sh`. It takes the version from `Cargo.toml` and installs the `.deb` from `target/debian/`, so run `cargo deb` first.