Merge branch 'development'

Author: keypair34

.agents/skills/distribution/SKILL.md

@@ -0,0 +1,226 @@
+---
+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 bundled native binary.
+
+Important details:
+
+- executable command should stay `onde`
+- use `Isolate.resolvePackageUri` to find the installed package path
+- keep the runtime-id mapping explicit
+- do not overcomplicate the wrapper with platform-specific Dart APIs unless necessary
+
+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:
+
+- files ignored by git are generally excluded from publish input
+
+That means staged native binaries for `pub/onde_cli/native/` must be available to the package at publish time.
+
+Two practical consequences:
+
+- do not ignore `pub/onde_cli/native/` in the root `.gitignore` if CI stages binaries there
+- a `.pubignore` can hide local tool noise, but do not hide the native payload you intend to publish
+
+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 package omits staged assets because gitignore excludes them
+- 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.

.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"

.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:

.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:

.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