onde-cli 0.3.0__tar.gz → 0.4.0__tar.gz

onde_cli-0.4.0/.agents/AGENTS.md

@@ -0,0 +1,69 @@
+# AGENTS.md
+
+`onde-cli` is a Rust TUI (`onde` binary) for managing an Onde Inference account and running a local model pipeline: LoRA fine-tune → adapter merge → GGUF export → local chat test → Hugging Face upload → model assignment to an Onde app. npm, PyPI, NuGet, pub.dev, Homebrew, and crates.io are thin wrappers around this one binary; the Rust crate is the source of truth.
+
+## Build, test, lint
+
+```sh
+cargo build                  # debug build
+cargo run                    # launch the TUI
+cargo run -- --mcp           # run as an MCP server over stdio (no TUI)
+cargo test --locked          # unit tests (heavy ones are #[ignore])
+cargo clippy --all-targets -- -D warnings
+cargo fmt -- --check
+```
+
+The build **requires** these env vars (read from `.env` via `build.rs`): `ONDE_APP_ID`, `ONDE_APP_SECRET`, `GRESIQ_API_KEY`, `GRESIQ_API_SECRET`. `HF_TOKEN` is optional. They are baked in at compile time via `env!(...)` in `src/app.rs`. Changing `.env` triggers a full rebuild.
+
+On macOS, candle's `metal` + `accelerate` features are added automatically. **Fine-tuning always runs on CPU** — Metal's backward pass in candle 0.10.2 produces corrupt gradients (1e6–1e29 in magnitude, where CPU gives ~40–65 for identical losses). Use `ONDE_FINETUNE_METAL=1` only to test newer candle versions, and verify with `ONDE_FINETUNE_GRAD_DEBUG=1` (per-step loss/max_abs/norm).
+
+Linux CI requires `libclang-dev` (`sudo apt-get install -y libclang-dev`).
+
+### Tests that load real models
+
+`src/gguf.rs` has two `#[ignore]` integration tests that export a ~1GB GGUF and run inference through `onde::mistralrs`. They need a Qwen3-0.6B model cached in the Onde App Group container and skip gracefully when it is absent.
+
+```sh
+cargo test gguf::tests::exported_qwen3_gguf_is_runnable -- --ignored --nocapture
+cargo test gguf::tests::finetune_merge_export_run     -- --ignored --nocapture
+```
+
+Env knobs for these: `ONDE_TEST_MODEL_DIR`, `ONDE_TEST_DTYPE` (`f16`/`q8_0`), `ONDE_TEST_LR`, `ONDE_TEST_DATA_PATH`, `ONDE_TEST_EPOCHS`, `ONDE_TEST_MAX_SEQ_LEN`, `ONDE_TEST_EVAL_PROMPT` (`||`-separated prompts), `ONDE_TEST_SYSTEM_PROMPT`. This makes the full-pipeline test double as a headless fine-tune runner for a custom dataset.
+
+### Debugging the TUI
+
+`main.rs` redirects both stdout and stderr to `~/.cache/onde/debug.log` before ratatui takes the alternate screen, because `mistral.rs` writes to both fds and would otherwise tear up the display. To see what the app or the inference engine is doing, tail that log; `println!`/`eprintln!`/`log::*` all land there, not on screen.
+
+## Architecture — `src/`
+
+| File(s) | Responsibility |
+|---|---|
+| `main.rs` | Entry point; redirects stdout/stderr to `~/.cache/onde/debug.log` before ratatui takes over |
+| `app.rs` | `App` struct + `Screen` state machine + `AuthEvent` channel (`tokio::select!` over an `mpsc` channel and a `crossterm` `EventStream`); `App::apply` folds background progress into state |
+| `ui.rs` | Pure ratatui render of `App`; no SDK imports (re-exports types through `app.rs`) |
+| `finetune.rs` | Hand-written LoRA trainer (candle, CPU): Qwen forward pass (RMSNorm, RoPE, GQA, optional Qwen3 QK-norm), LoRA A/B trained on q/v projections in F32, writes `lora_adapter.safetensors`. Gradients are sanitized (non-finite elements zeroed) and globally norm-clipped in a scaled space before each AdamW step; a step is skipped (loudly) only when the norm is zero or non-finite. **Skipping this guard corrupts every weight after the first bad step.** |
+| `merge.rs` | Folds LoRA adapter into base weights (`W + scale·(B@A)`); writes `model.safetensors` plus copied config/tokenizer |
+| `gguf.rs` | Hand-rolled GGUF writer (no llama.cpp). Tensor dims are written innermost-first — reverse of safetensors shape, because candle reverses on read; `head_dim` comes from config and is emitted as `attention.key_length`/`value_length` (Qwen3 decouples it from `hidden_size/num_heads`); `token_type` is an INT32 array; `general.architecture` is chosen from `model_type` so Qwen3 routes to candle's `quantized_qwen3` loader |
+| `chat.rs` | Local GGUF chat via `onde::mistralrs::GgufModelBuilder`, the same engine the Onde SDK uses, so a model can be tested before publishing |
+| `hf_upload.rs` / `hf_clone.rs` / `hf_search.rs` / `hf.rs` | Hugging Face Hub: upload the GGUF, check/create a repo, search models, and resolve/merge the local HF cache (incl. the macOS Onde App Group container) |
+| `gresiq.rs` | `smbcloud-gresiq-sdk` wrapper for apps and the model catalog. "Deploying" a model means `assign_model(app_id, model_id)` against a catalog entry; the end app then fetches that assignment through the Onde SDK's `load_assigned_model` and downloads the GGUF. The CLI can only assign models that already exist in the GresIQ catalog |
+| `token.rs` | Auth token persistence |
+| `project.rs` | Per-project fine-tune workspaces under `~/.onde` |
+
+**Background task rule:** network/IO → `tokio::spawn`; CPU-heavy tensor work (`finetune`, `merge`, `gguf`) → `std::thread::spawn` to avoid starving the async runtime.
+
+**Adding a feature pattern:** new `Screen` variant → key handler → `AuthEvent` variant → background task that streams progress events.
+
+### The `onde` dependency
+
+The `onde` crate provides the inference engine (`onde::mistralrs`, a vendored mistral.rs) and `onde::inference::models::SUPPORTED_MODEL_INFO` (the supported-model catalog the inference picker mirrors). It is normally the published crate; `Cargo.toml` has commented `path`/`[patch.crates-io]` blocks for developing against local checkouts of `onde`, the `smbcloud-*` crates, and `candle` — never commit with those uncommented.
+
+## Conventions
+
+- **Git:** merge feature/release/hotfix branches with `--no-ff`. Tag the merge commit on `main`. Never tag a branch tip that hasn't been merged. See `.agents/skills/git/SKILL.md`.
+- **Commits:** include `Co-Authored-By: siGit Code <297239231+sigitc@users.noreply.github.com>` trailer when committing with the agent.
+- **`[patch.crates-io]` and `path =` deps:** commented out in `Cargo.toml` for local dev against `onde`/`smbcloud-*`/`candle`. Never commit with these uncommented.
+- **Distribution:** before touching any wrapper package (npm, PyPI, NuGet, pub.dev, Homebrew), read `.agents/skills/distribution/SKILL.md`. Keep all channel versions aligned with the Rust crate version in `Cargo.toml`.
+- **Wrapper packages** are in `npm/`, `pypi/`, `nuget/`, `pub/`. The npm base manifest is rewritten at release time by `npm/scripts/render-main-package.cjs`; do not hand-edit committed package.json versions as the source of truth for releases.
+- **Clippy** runs with `-D warnings` in CI; all lints must pass.
+- **Rust edition:** 2024; toolchain: stable.

onde_cli-0.4.0/.agents/skills/distribution/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: distribution
+description: Use when adding, fixing, or documenting package distribution for Onde CLI. Covers wrapper-package design across npm, PyPI, NuGet, pub.dev, GitHub Releases, and Homebrew, plus version alignment, artifact staging, README surfaces, and smoke-test strategy.
+---
+
+# Onde CLI distribution
+
+This skill captures how `onde-cli` is distributed today and what to watch when adding new channels.
+
+## Distribution model
+
+`onde-cli` is a native Rust CLI first.
+
+Everything else is packaging.
+
+That means:
+
+- build the Rust binary once per target
+- publish thin wrappers that install or launch that binary
+- keep channel-specific logic small and predictable
+
+This design keeps behavior consistent across ecosystems and avoids re-implementing CLI logic in each language.
+
+## Channel map
+
+### Native source of truth
+
+- Rust crate: `onde-cli`
+- binary name: `onde`
+- root manifest: `Cargo.toml`
+
+### Wrapper channels
+
+- npm: JavaScript launcher + optional platform packages
+- PyPI: `maturin` binary wheels
+- NuGet: .NET global tool launcher
+- pub.dev: Dart launcher package
+
+### Native artifact channels
+
+- crates.io
+- GitHub Releases
+- Homebrew
+
+## Wrapper design patterns
+
+### npm
+
+Use a very small Node launcher that:
+
+- detects OS and architecture
+- resolves the installed platform package
+- spawns the binary with inherited stdio
+
+Good fit for users who already live in npm tooling.
+
+Important release detail:
+
+- the committed `npm/onde-cli/package.json` is a working file, not the publish-time source of truth
+- the release workflow rewrites the base package manifest with `npm/scripts/render-main-package.cjs`
+- platform package manifests are generated on the fly with `npm/scripts/render-platform-package.cjs`
+- the actual npm version comes from the release tag via `RELEASE_VERSION`, not from manually editing the committed npm manifest before publish
+
+### PyPI
+
+Use `maturin` with `bindings = "bin"` so the native executable is what gets installed.
+
+Good fit for Python users who want the CLI but not a Python reimplementation.
+
+### NuGet
+
+Use a `.NET global tool` wrapper.
+
+Important details:
+
+- keep the package as a launcher, not a managed rewrite
+- place native binaries under the tool payload
+- resolve the runtime identifier at startup
+- set Unix execute bits before launch
+
+Good fit for .NET developers and CI environments that already use `dotnet tool install`.
+
+### pub.dev
+
+Use a Dart package with a command entrypoint and a library that launches the native binary.
+
+Important details:
+
+- executable command should stay `onde`
+- keep the runtime-id mapping explicit
+- download the correct binary from GitHub Releases on first run
+- cache downloads under `~/.onde/cli`
+- keep the wrapper thin, the Rust binary is still the product
+- publish the pub.dev package only after the matching GitHub Release exists
+
+Good fit for Dart and Flutter developers who want the same CLI through familiar tooling.
+
+## Runtime identifier mapping
+
+Keep these names aligned anywhere wrappers or workflows refer to native assets:
+
+- `darwin-x64`
+- `darwin-arm64`
+- `linux-x64`
+- `linux-arm64`
+- `windows-x64`
+- `windows-arm64`
+
+If a wrapper uses one naming scheme and a workflow uploads another, the installed package will pass packaging but fail at runtime.
+
+## Release workflow principles
+
+### Build first, package second
+
+Always build native binaries in a target matrix first.
+
+Then let the wrapper channel jobs package those artifacts.
+
+This avoids rebuilding the product multiple times and makes failures easier to reason about.
+
+### Idempotency
+
+Every publish workflow should check whether the target version already exists before publishing.
+
+Examples:
+
+- npm: `npm view`
+- PyPI: package JSON endpoint
+- NuGet: flat container index
+- pub.dev: package API endpoint
+
+### Smoke tests should match the product shape
+
+Because `onde` is TUI-first, avoid smoke tests that assume a traditional CLI help flow unless you know that code path is stable and non-interactive.
+
+Safer checks:
+
+- install succeeds
+- bundled native binary exists where expected
+- package manager validation passes
+
+## pub.dev-specific notes
+
+pub.dev behaves differently from npm and NuGet in one important way:
+
+- large bundled binaries quickly hit package size limits
+
+That makes the safest design a thin Dart launcher that downloads the right native binary from GitHub Releases at runtime instead of shipping every platform binary inside the package.
+
+Practical consequences:
+
+- `pub/onde_cli/native/` should stay out of the published package
+- do not set `publish_to: https://pub.dev` in `pubspec.yaml`; omit `publish_to` for normal pub.dev publishing
+- use package-level ignore rules so local native staging does not leak into publish input
+- keep release asset names aligned with the GitHub Release workflow, because the launcher depends on them
+- treat `~/.onde/cli` as the local cache root for downloaded binaries
+- do not let the pub.dev workflow race ahead of GitHub Releases; dispatch it after `release-github.yml` has created the assets
+
+Run these during verification:
+
+- `dart pub get --directory pub/onde_cli`
+- `dart analyze pub/onde_cli`
+- `dart pub publish --dry-run --directory pub/onde_cli`
+
+## NuGet-specific notes
+
+NuGet packaging is sensitive to path layout.
+
+The safest pattern is:
+
+- copy native files into the publish output
+- let the .NET tool pack process carry them into the final package
+
+Avoid custom `PackagePath` patterns that can duplicate path segments or create nested native folders by accident.
+
+If the tool installs but cannot find the native binary, inspect the `.nupkg` contents before debugging the launcher.
+
+## README surfaces
+
+Every user-facing channel should document the same product with channel-specific installation instructions.
+
+Main files:
+
+- `README.md`
+- `npm/onde-cli/README.md`
+- `pypi/README.md`
+- `nuget/onde-cli/README.md`
+- `pub/onde_cli/README.md`
+
+Keep these aligned on:
+
+- product description
+- supported platforms
+- install method
+- license and copyright
+- relevant supporting links like the forward-pass explainer
+
+Do not let one channel sound like a different product.
+
+## Version alignment
+
+When cutting a release, update every user-facing distribution version that should move with the CLI.
+
+At minimum, check:
+
+- Rust crate version
+- npm release templates and workflow assumptions
+- npm lockfile version if committed
+- PyPI release version source
+- NuGet package version at pack time
+- pub.dev package version in `pubspec.yaml`
+- workflow example tags and docs that mention concrete versions
+
+## Common failure modes
+
+- wrapper version does not match the Rust release version
+- manually bumping the committed npm manifest and assuming that is what npm publishes
+- staged native binaries land in the wrong directory before packaging
+- package builds successfully but installs without the native binary
+- pub.dev launcher points at the wrong GitHub Release asset name or runtime id
+- pub.dev workflow publishes before the matching GitHub Release assets exist
+- pub.dev package still includes bundled binaries and blows the upload size limit
+- smoke test invokes a TUI-first binary in a way that does not make sense for CI
+- README badges and install commands drift out of sync with real package names
+
+## Rule of thumb
+
+If the native binary works and the wrappers are boring, distribution stays manageable.
+
+If a wrapper starts acting like its own product, complexity grows fast.
+
+Keep it thin.
+Keep it aligned.
+Keep the Rust binary as the source of truth.

onde_cli-0.4.0/.agents/skills/git/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: git
+description: Git workflow rules for this repository.
+allowed-tools: Read, Write, Edit, Glob, Grep, AskUserQuestion
+user-invocable: true
+---
+
+# Git skill
+
+## Core rule
+
+- Use `--no-ff`. Important.
+
+## What this means in practice
+
+- Do not fast-forward merge feature branches, release branches, or hotfix branches.
+- Prefer explicit merge commits so the branch history stays visible.
+- Release prep goes through `development` on its way to `main`, with `--no-ff` at every hop.
+- Tag the merge commit that contains the final release state.
+
+## Branch flow
+
+Feature branches merge into `development`. Releases go:
+
+```
+release/vX.Y.Z -> development -> main
+```
+
+Never merge a release branch straight into `main` — `development` has to carry the
+release state too, or the next feature branch starts from a base that is missing it.
+
+## Release guidance
+
+```bash
+# 1. cut the release branch from development, commit the version bumps
+git checkout development
+git checkout -b release/vX.Y.Z
+git commit -am "Prepare vX.Y.Z"
+
+# 2. release branch -> development
+git checkout development
+git merge --no-ff release/vX.Y.Z -m "Merge release prep for vX.Y.Z"
+
+# 3. development -> main
+git checkout main
+git merge --no-ff development -m "Merge development for vX.Y.Z"
+
+# 4. tag the main merge commit, then push
+git tag vX.Y.Z
+git push origin development
+git push origin main
+git push origin vX.Y.Z
+```
+
+The tag belongs on the step-3 merge commit on `main`, not on the release branch and not
+on `development`. Pushing the tag is what triggers the wrapper publish workflows, which
+read the version from the tag.
+
+If the work is already on `main`, make a normal commit and tag that commit. Do not rewrite history just to avoid a merge commit.
+
+## Avoid
+
+- `git merge --ff`
+- `git pull --ff-only` as a default recommendation for this repo's merge policy
+- Tagging a branch tip that has not been merged into `main` when the intended release source of truth is `main`
+- Merging a release branch directly into `main`, skipping `development`
+
+## Why
+
+The repo wants explicit history. Release commits should be easy to find, easy to audit, and clearly connected to the branch that introduced them.

{onde_cli-0.3.0 → onde_cli-0.4.0}/.github/workflows/ci.yml

@@ -108,6 +108,39 @@ jobs:
           GRESIQ_API_SECRET: ${{ secrets.GRESIQ_API_SECRET }}
           HF_TOKEN: ${{ secrets.HF_TOKEN }}
 
+  dotnet-tool:
+    name: .NET tool launcher build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 8.0.x
+
+      - name: Build .NET tool launcher
+        run: dotnet build nuget/onde-cli/Onde.Cli.csproj --configuration Release
+
+  dart-package:
+    name: Dart pub package check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Dart SDK
+        uses: dart-lang/setup-dart@v1
+
+      - name: Get package dependencies
+        working-directory: pub/onde_cli
+        run: dart pub get
+
+      - name: Analyze Dart package
+        working-directory: pub/onde_cli
+        run: dart analyze
+
   build:
     name: Build (aarch64-apple-darwin)
     runs-on: macos-26
@@ -140,13 +173,17 @@ jobs:
       - clippy
       - test
       - check
+      - dotnet-tool
+      - dart-package
       - build
     if: always()
     steps:
       - name: Verify all required jobs succeeded
         run: |
-          test "${{ needs.fmt.result }}"    = "success"
-          test "${{ needs.clippy.result }}" = "success"
-          test "${{ needs.test.result }}"   = "success"
-          test "${{ needs.check.result }}"  = "success"
-          test "${{ needs.build.result }}"  = "success"
+          test "${{ needs.fmt.result }}"         = "success"
+          test "${{ needs.clippy.result }}"      = "success"
+          test "${{ needs.test.result }}"        = "success"
+          test "${{ needs.check.result }}"        = "success"
+          test "${{ needs.dotnet-tool.result }}"  = "success"
+          test "${{ needs.dart-package.result }}" = "success"
+          test "${{ needs.build.result }}"        = "success"

{onde_cli-0.3.0 → onde_cli-0.4.0}/.github/workflows/release-github.yml

@@ -7,7 +7,7 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: "Release tag (e.g. v0.1.1)"
+        description: "Release tag (e.g. v0.3.1)"
         required: true
 
 permissions:
@@ -190,3 +190,18 @@ jobs:
               }
             })
             console.log('Dispatched release-homebrew.yml for tag ${{ steps.tag.outputs.tag }}')
+
+      - name: Trigger pub.dev release
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.actions.createWorkflowDispatch({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: 'release-pub.yml',
+              ref: 'main',
+              inputs: {
+                tag: '${{ steps.tag.outputs.tag }}'
+              }
+            })
+            console.log('Dispatched release-pub.yml for tag ${{ steps.tag.outputs.tag }}')

{onde_cli-0.3.0 → onde_cli-0.4.0}/.github/workflows/release-homebrew.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: "Release tag (e.g. v0.1.1)"
+        description: "Release tag (e.g. v0.3.1)"
         required: true
 
 permissions:

{onde_cli-0.3.0 → onde_cli-0.4.0}/.github/workflows/release-npm.yml

@@ -7,7 +7,7 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: "Release tag (e.g. v0.2.0)"
+        description: "Release tag (e.g. v0.3.1)"
         required: true
 
 permissions:
@@ -55,11 +55,7 @@ jobs:
               OS: macos-26-intel,
               TARGET: x86_64-apple-darwin,
             }
-          - {
-              NAME: darwin-arm64,
-              OS: macos-26,
-              TARGET: aarch64-apple-darwin,
-            }
+          - { NAME: darwin-arm64, OS: macos-26, TARGET: aarch64-apple-darwin }
 
     steps:
       - name: Checkout