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

onde_cli-0.3.1/.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.

{onde_cli-0.3.0 → onde_cli-0.3.1}/.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.3.1}/.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:

{onde_cli-0.3.0 → onde_cli-0.3.1}/.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.3.1}/.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

onde_cli-0.3.1/.github/workflows/release-nuget.yml

@@ -0,0 +1,305 @@
+name: NuGet Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag (e.g. v0.3.1)"
+        required: true
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+  DOTNET_VERSION: 8.0.x
+  NUGET_PACKAGE_ID: Onde.Cli
+  ONDE_APP_ID: ${{ secrets.ONDE_APP_ID }}
+  ONDE_APP_SECRET: ${{ secrets.ONDE_APP_SECRET }}
+  GRESIQ_API_KEY: ${{ secrets.GRESIQ_API_KEY }}
+  GRESIQ_API_SECRET: ${{ secrets.GRESIQ_API_SECRET }}
+  HF_TOKEN: ${{ secrets.HF_TOKEN }}
+
+jobs:
+  build-native-binaries:
+    name: Build native binary (${{ matrix.build.NAME }})
+    runs-on: ${{ matrix.build.OS }}
+    strategy:
+      fail-fast: false
+      matrix:
+        build:
+          - {
+              NAME: linux-x64,
+              OS: ubuntu-latest,
+              TARGET: x86_64-unknown-linux-gnu,
+            }
+          - {
+              NAME: linux-arm64,
+              OS: ubuntu-24.04-arm,
+              TARGET: aarch64-unknown-linux-gnu,
+            }
+          - {
+              NAME: windows-x64,
+              OS: windows-2022,
+              TARGET: x86_64-pc-windows-msvc,
+            }
+          - {
+              NAME: windows-arm64,
+              OS: windows-2022,
+              TARGET: aarch64-pc-windows-msvc,
+            }
+          - {
+              NAME: darwin-x64,
+              OS: macos-26-intel,
+              TARGET: x86_64-apple-darwin,
+            }
+          - { NAME: darwin-arm64, OS: macos-26, TARGET: aarch64-apple-darwin }
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.inputs.tag || github.ref }}
+
+      - name: Set the release version
+        shell: bash
+        run: |
+          if [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            release_version="${GITHUB_REF_NAME#v}"
+          else
+            release_version="${{ github.event.inputs.tag }}"
+            release_version="${release_version#v}"
+          fi
+
+          echo "RELEASE_VERSION=${release_version}" >> "$GITHUB_ENV"
+
+      - name: Read Rust toolchain
+        shell: bash
+        run: |
+          rust_toolchain="$(sed -n 's/^channel = "\(.*\)"/\1/p' rust-toolchain.toml | head -n 1)"
+          if [ -z "$rust_toolchain" ]; then
+            echo "Failed to read Rust toolchain from rust-toolchain.toml" >&2
+            exit 1
+          fi
+
+          echo "RUST_TOOLCHAIN=${rust_toolchain}" >> "$GITHUB_ENV"
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9
+        with:
+          toolchain: ${{ env.RUST_TOOLCHAIN }}
+          targets: ${{ matrix.build.TARGET }}
+
+      - name: Setup Rust cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          key: nuget-${{ matrix.build.TARGET }}
+
+      - name: Build binary
+        shell: bash
+        run: cargo build --locked --release --target ${{ matrix.build.TARGET }}
+
+      - name: Prepare artifact
+        shell: bash
+        run: |
+          executable_name="onde"
+          if [[ "${{ matrix.build.OS }}" == "windows-2022" ]]; then
+            executable_name="onde.exe"
+          fi
+
+          mkdir -p "nuget-artifacts/native/${{ matrix.build.NAME }}"
+          cp "target/${{ matrix.build.TARGET }}/release/${executable_name}" "nuget-artifacts/native/${{ matrix.build.NAME }}/${executable_name}"
+
+      - name: Upload native artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: nuget-native-${{ matrix.build.NAME }}
+          path: nuget-artifacts/native
+
+  pack-nuget:
+    name: Pack NuGet .NET tool
+    runs-on: ubuntu-latest
+    needs: build-native-binaries
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.inputs.tag || github.ref }}
+
+      - name: Set the release version
+        shell: bash
+        run: |
+          if [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            release_version="${GITHUB_REF_NAME#v}"
+          else
+            release_version="${{ github.event.inputs.tag }}"
+            release_version="${release_version#v}"
+          fi
+
+          echo "RELEASE_VERSION=${release_version}" >> "$GITHUB_ENV"
+
+      - name: Download native artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: nuget-native-*
+          path: nuget/onde-cli/native
+          merge-multiple: true
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: ${{ env.DOTNET_VERSION }}
+
+      - name: Pack .NET tool
+        shell: bash
+        run: |
+          dotnet pack nuget/onde-cli/Onde.Cli.csproj \
+            --configuration Release \
+            --output nuget/dist \
+            -p:PackageVersion=${RELEASE_VERSION}
+
+      - name: Upload package artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: nuget-package
+          path: nuget/dist/*.nupkg
+
+  smoke-test:
+    name: Smoke test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    needs: pack-nuget
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-2022
+          - macos-26
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.inputs.tag || github.ref }}
+
+      - name: Set the release version
+        shell: bash
+        run: |
+          if [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            release_version="${GITHUB_REF_NAME#v}"
+          else
+            release_version="${{ github.event.inputs.tag }}"
+            release_version="${release_version#v}"
+          fi
+
+          echo "RELEASE_VERSION=${release_version}" >> "$GITHUB_ENV"
+
+      - name: Download package artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: nuget-package
+          path: nuget/dist
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: ${{ env.DOTNET_VERSION }}
+
+      - name: Install tool from local package
+        shell: pwsh
+        run: |
+          $packageSource = (Resolve-Path "nuget/dist").Path
+          @"
+          <?xml version="1.0" encoding="utf-8"?>
+          <configuration>
+            <packageSources>
+              <clear />
+              <add key="local" value="$packageSource" />
+            </packageSources>
+          </configuration>
+          "@ | Set-Content -Path "nuget/NuGet.Config"
+
+          dotnet tool install `
+            --tool-path ".tool" `
+            --configfile "nuget/NuGet.Config" `
+            --version "$env:RELEASE_VERSION" `
+            "$env:NUGET_PACKAGE_ID"
+
+      - name: Verify bundled native binary
+        shell: pwsh
+        run: |
+          $runtimeIdentifier = if ($IsWindows) {
+            if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq [System.Runtime.InteropServices.Architecture]::Arm64) { "windows-arm64" } else { "windows-x64" }
+          } elseif ($IsMacOS) {
+            if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq [System.Runtime.InteropServices.Architecture]::Arm64) { "darwin-arm64" } else { "darwin-x64" }
+          } else {
+            if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq [System.Runtime.InteropServices.Architecture]::Arm64) { "linux-arm64" } else { "linux-x64" }
+          }
+
+          $binaryName = if ($IsWindows) { "onde.exe" } else { "onde" }
+          $nativeBinary = Get-ChildItem ".tool/.store" -Recurse -File | Where-Object {
+            $_.FullName -like "*native*${runtimeIdentifier}*${binaryName}"
+          } | Select-Object -First 1
+
+          if (-not $nativeBinary) {
+            Write-Error "Onde native binary for ${runtimeIdentifier} was not bundled in the installed .NET tool package."
+          }
+
+          Write-Host "Found bundled native binary at $($nativeBinary.FullName)"
+
+  publish-nuget:
+    name: Publish to NuGet
+    runs-on: ubuntu-latest
+    needs: smoke-test
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.inputs.tag || github.ref }}
+
+      - name: Set the release version
+        shell: bash
+        run: |
+          if [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            release_version="${GITHUB_REF_NAME#v}"
+          else
+            release_version="${{ github.event.inputs.tag }}"
+            release_version="${release_version#v}"
+          fi
+
+          echo "RELEASE_VERSION=${release_version}" >> "$GITHUB_ENV"
+
+      - name: Download package artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: nuget-package
+          path: nuget/dist
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: ${{ env.DOTNET_VERSION }}
+
+      - name: Check whether release already exists on NuGet
+        id: nuget-check
+        shell: bash
+        run: |
+          package_index_url="https://api.nuget.org/v3-flatcontainer/onde.cli/index.json"
+          if curl -fsS "${package_index_url}" | grep -F "\"${RELEASE_VERSION}\"" >/dev/null; then
+            echo "${NUGET_PACKAGE_ID} ${RELEASE_VERSION} already exists on NuGet, skipping publish"
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Publish package
+        if: steps.nuget-check.outputs.exists != 'true'
+        env:
+          NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}
+        shell: bash
+        run: |
+          dotnet nuget push nuget/dist/*.nupkg \
+            --api-key "${NUGET_API_KEY}" \
+            --source https://api.nuget.org/v3/index.json \
+            --skip-duplicate