Feat:package manager channels (brew, apt, npm ) (tinyhumansai#166)

* feat(release): upload versioned CLI tarballs in release workflow (tinyhumansai#128)

Package and upload non-Windows CLI tarballs with SHA-256 checksum companions during release builds so package managers can consume stable release artifacts.

Made-with: Cursor

* feat(packaging): add brew apt npm release channels automation (tinyhumansai#128)

Add post-release workflow and channel assets to publish Homebrew formula updates, signed apt repository metadata, and npm package releases with smoke validation.

Made-with: Cursor

* docs: add installation guide for OpenHuman across various package managers

Author: YellowSnnowmann

.github/workflows/release-packages.yml

@@ -678,6 +678,48 @@ jobs:
           echo "Checking staple..."
           xcrun stapler validate "$APP_PATH" || echo "WARNING: Staple validation failed"
 
+      - name: Package CLI tarball and upload to release
+        if: matrix.settings.platform != 'windows-latest'
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ needs.prepare-release.outputs.version }}
+          MATRIX_PLATFORM: ${{ matrix.settings.platform }}
+          MATRIX_TARGET: ${{ matrix.settings.target }}
+        run: |
+          set -euo pipefail
+
+          TARBALL="openhuman-core-${VERSION}-${MATRIX_TARGET}.tar.gz"
+          WORK=$(mktemp -d)
+          trap 'rm -rf "$WORK"' EXIT
+
+          if [[ "$MATRIX_PLATFORM" == "macos-latest" ]]; then
+            # Prefer the notarized+signed binary extracted from inside the .app bundle
+            APP_PATH="${{ steps.locate-app.outputs.app_path }}"
+            BIN=$(find "$APP_PATH/Contents/MacOS" -maxdepth 1 -name "openhuman-core-*" \
+              ! -name "*.sig" 2>/dev/null | head -1 || true)
+            [[ -z "$BIN" ]] && BIN=$(find "$APP_PATH/Contents/Resources" -maxdepth 1 \
+              -name "openhuman-core-*" ! -name "*.sig" 2>/dev/null | head -1 || true)
+            if [[ -z "$BIN" ]]; then
+              echo "[pkg] Falling back to target dir binary (no notarized sidecar found)"
+              BIN="${{ steps.cli-paths.outputs.cli_path }}"
+            fi
+          else
+            BIN="${{ steps.cli-paths.outputs.cli_path }}"
+          fi
+
+          cp "$BIN" "$WORK/openhuman-core"
+          chmod +x "$WORK/openhuman-core"
+          tar -czf "$TARBALL" -C "$WORK" openhuman-core
+
+          # openssl dgst works on both macOS and Linux runners
+          openssl dgst -sha256 -r "$TARBALL" | awk '{print $1}' > "${TARBALL}.sha256"
+
+          gh release upload "v${VERSION}" "$TARBALL" "${TARBALL}.sha256" \
+            --repo tinyhumansai/openhuman --clobber
+
+          echo "[pkg] Uploaded $TARBALL and ${TARBALL}.sha256"
+
       - name: Upload standalone CLI artifacts
         uses: actions/upload-artifact@v4
         with:

.github/workflows/release.yml

@@ -0,0 +1,199 @@
+# Installing OpenHuman
+
+## Quick install
+
+| Package manager | Command | OS |
+|---|---|---|
+| **Homebrew** | `brew install tinyhumansai/openhuman/openhuman` | macOS, Linux |
+| **apt** | `sudo apt install openhuman` (see [setup](#apt-debianubuntu)) | Debian, Ubuntu |
+| **npm** | `npm install -g openhuman` | Any (Node ≥ 18) |
+| **curl** | `curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh \| bash` | macOS, Linux |
+
+---
+
+## Homebrew (macOS / Linux)
+
+```bash
+brew install tinyhumansai/openhuman/openhuman
+```
+
+**Update:**
+```bash
+brew upgrade openhuman
+```
+
+**Uninstall:**
+```bash
+brew uninstall openhuman
+brew untap tinyhumansai/openhuman   # optional: remove tap
+```
+
+Homebrew installs the binary as `openhuman`. The tap lives at
+[tinyhumansai/homebrew-openhuman](https://github.com/tinyhumansai/homebrew-openhuman).
+
+---
+
+## apt (Debian / Ubuntu)
+
+### 1. Add the repository key and source
+
+```bash
+sudo apt-get install -y gnupg2 curl ca-certificates
+
+curl -fsSL https://tinyhumansai.github.io/openhuman/apt/KEY.gpg \
+  | sudo gpg --dearmor -o /etc/apt/keyrings/openhuman.gpg
+
+echo "deb [signed-by=/etc/apt/keyrings/openhuman.gpg arch=amd64] \
+  https://tinyhumansai.github.io/openhuman/apt stable main" \
+  | sudo tee /etc/apt/sources.list.d/openhuman.list
+```
+
+> **arm64:** replace `arch=amd64` with `arch=arm64` or `arch=amd64,arm64`.
+
+### 2. Install
+
+```bash
+sudo apt-get update
+sudo apt-get install openhuman
+```
+
+**Update:**
+```bash
+sudo apt-get update && sudo apt-get upgrade openhuman
+```
+
+**Uninstall:**
+```bash
+sudo apt-get remove openhuman
+# remove repository (optional):
+sudo rm /etc/apt/sources.list.d/openhuman.list /etc/apt/keyrings/openhuman.gpg
+```
+
+---
+
+## npm
+
+```bash
+npm install -g openhuman
+```
+
+**Update:**
+```bash
+npm update -g openhuman
+```
+
+**Uninstall:**
+```bash
+npm uninstall -g openhuman
+```
+
+The npm package is a thin wrapper that downloads the platform-native binary on
+first install and verifies its SHA-256 checksum before placing it. Node.js ≥ 18
+is required; the binary itself has no Node dependency at runtime.
+
+---
+
+## curl / manual install
+
+```bash
+curl -fsSL \
+  https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh \
+  | bash
+```
+
+Pass `--dry-run` to preview actions without installing:
+
+```bash
+bash scripts/install.sh --dry-run --verbose
+```
+
+**Uninstall (manual):**
+```bash
+rm "$(which openhuman)"
+```
+
+---
+
+## Support policy
+
+| Channel | Tier | Maintained by |
+|---|---|---|
+| Homebrew | **Official** | Core team |
+| apt | **Official** | Core team |
+| npm | **Official** | Core team |
+| curl / install.sh | **Official** | Core team |
+| AUR (Arch) | Community | Community PRs |
+| Nix | Community | Community PRs |
+| Scoop (Windows) | Planned | — |
+| Snap / Flatpak | Planned | — |
+
+See [tinyhumansai/openhuman#distribution-backlog](https://github.com/tinyhumansai/openhuman/issues?q=label%3Adistribution-backlog) for the next channels in the pipeline.
+
+---
+
+## Troubleshooting
+
+### macOS Gatekeeper warning
+
+If macOS blocks the binary with *"cannot be opened because the developer cannot be verified"*:
+
+```bash
+# Option 1: approve via System Settings → Privacy & Security → Allow Anyway
+# Option 2: remove quarantine flag (Homebrew install should handle this automatically)
+xattr -d com.apple.quarantine "$(which openhuman)"
+```
+
+Binaries installed via Homebrew or the signed `.app` bundle are notarized by
+Apple and should not trigger Gatekeeper.
+
+### apt: "NO_PUBKEY" error
+
+Re-import the key:
+```bash
+curl -fsSL https://tinyhumansai.github.io/openhuman/apt/KEY.gpg \
+  | sudo gpg --dearmor -o /etc/apt/keyrings/openhuman.gpg
+sudo apt-get update
+```
+
+### npm: binary not found after install
+
+The postinstall script may have failed silently. Re-run it manually:
+```bash
+FORCE_REINSTALL=1 node "$(npm root -g)/openhuman/install.js"
+```
+
+Or reinstall cleanly:
+```bash
+npm uninstall -g openhuman && npm install -g openhuman
+```
+
+### Verify checksum manually
+
+Every release asset ships a companion `.sha256` file:
+
+```bash
+VERSION=0.49.33
+TARGET=x86_64-unknown-linux-gnu
+curl -fsSLO "https://github.com/tinyhumansai/openhuman/releases/download/v${VERSION}/openhuman-core-${VERSION}-${TARGET}.tar.gz"
+curl -fsSLO "https://github.com/tinyhumansai/openhuman/releases/download/v${VERSION}/openhuman-core-${VERSION}-${TARGET}.tar.gz.sha256"
+echo "$(cat openhuman-core-${VERSION}-${TARGET}.tar.gz.sha256)  openhuman-core-${VERSION}-${TARGET}.tar.gz" | sha256sum --check
+```
+
+---
+
+## Release artifacts reference
+
+Each release attaches the following files:
+
+| Artifact | Platform |
+|---|---|
+| `openhuman-core-<v>-aarch64-apple-darwin.tar.gz` | macOS Apple Silicon |
+| `openhuman-core-<v>-x86_64-apple-darwin.tar.gz` | macOS Intel |
+| `openhuman-core-<v>-x86_64-unknown-linux-gnu.tar.gz` | Linux x86-64 |
+| `openhuman-core-<v>-aarch64-unknown-linux-gnu.tar.gz` | Linux arm64 |
+| `OpenHuman_<v>_aarch64.dmg` | macOS desktop app (Apple Silicon) |
+| `OpenHuman_<v>_x64.dmg` | macOS desktop app (Intel) |
+| `OpenHuman_<v>_amd64.deb` | Linux desktop app (.deb) |
+| `OpenHuman_<v>_amd64.AppImage` | Linux desktop app (AppImage) |
+
+Every archive has a corresponding `.sha256` companion file.

docs/install.md

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Build a .deb package for the openhuman-core CLI binary.
+# Usage: build.sh <binary_path> <version> <arch>
+#   arch: amd64 | arm64
+set -euo pipefail
+
+BINARY="$1"
+VERSION="$2"
+ARCH="$3"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="$(mktemp -d)"
+trap 'rm -rf "$WORK_DIR"' EXIT
+
+PKG_NAME="openhuman_${VERSION}_${ARCH}"
+PKG_DIR="$WORK_DIR/$PKG_NAME"
+
+mkdir -p "$PKG_DIR/usr/bin"
+mkdir -p "$PKG_DIR/DEBIAN"
+
+install -m 755 "$BINARY" "$PKG_DIR/usr/bin/openhuman"
+
+sed \
+  -e "s/@VERSION@/${VERSION}/g" \
+  -e "s/@ARCH@/${ARCH}/g" \
+  "$SCRIPT_DIR/control.in" > "$PKG_DIR/DEBIAN/control"
+
+OUTPUT="${PKG_NAME}.deb"
+dpkg-deb --build --root-owner-group "$PKG_DIR" "$OUTPUT"
+echo "[deb] Built: $OUTPUT"

packages/deb/build.sh

@@ -0,0 +1,10 @@
+Package: openhuman
+Version: @VERSION@
+Section: utils
+Priority: optional
+Architecture: @ARCH@
+Maintainer: OpenHuman <hello@tinyhumans.ai>
+Homepage: https://github.com/tinyhumansai/openhuman
+Description: AI-powered assistant for communities
+ OpenHuman is an AI-powered CLI for crypto communities and
+ collaborative workspaces.

packages/deb/control.in

@@ -0,0 +1,39 @@
+# Homebrew formula template — rendered by CI, committed to tinyhumansai/homebrew-openhuman.
+# Placeholders replaced by .github/workflows/release-packages.yml before commit.
+class Openhuman < Formula
+  desc "AI-powered assistant for communities — OpenHuman CLI"
+  homepage "https://github.com/tinyhumansai/openhuman"
+  version "@VERSION@"
+  license "MIT"
+
+  on_macos do
+    on_arm do
+      url "https://github.com/tinyhumansai/openhuman/releases/download/v@VERSION@/openhuman-core-@VERSION@-aarch64-apple-darwin.tar.gz"
+      sha256 "@SHA256_MACOS_ARM64@"
+    end
+    on_intel do
+      url "https://github.com/tinyhumansai/openhuman/releases/download/v@VERSION@/openhuman-core-@VERSION@-x86_64-apple-darwin.tar.gz"
+      sha256 "@SHA256_MACOS_X64@"
+    end
+  end
+
+  on_linux do
+    on_arm do
+      # ARM64 (aarch64)
+      url "https://github.com/tinyhumansai/openhuman/releases/download/v@VERSION@/openhuman-core-@VERSION@-aarch64-unknown-linux-gnu.tar.gz"
+      sha256 "@SHA256_LINUX_ARM64@"
+    end
+    on_intel do
+      url "https://github.com/tinyhumansai/openhuman/releases/download/v@VERSION@/openhuman-core-@VERSION@-x86_64-unknown-linux-gnu.tar.gz"
+      sha256 "@SHA256_LINUX_X64@"
+    end
+  end
+
+  def install
+    bin.install "openhuman-core" => "openhuman"
+  end
+
+  test do
+    system "#{bin}/openhuman", "--version"
+  end
+end

packages/homebrew/openhuman.rb

@@ -0,0 +1,6 @@
+# Exclude the downloaded native binary from published package
+bin/openhuman-bin
+bin/openhuman-bin.exe
+bin/*.tar.gz
+bin/*.zip
+bin/*.sha256

packages/npm/.npmignore

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const isWin = process.platform === 'win32';
+const binName = isWin ? 'openhuman-bin.exe' : 'openhuman-bin';
+const binPath = path.join(__dirname, binName);
+
+const result = spawnSync(binPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  windowsHide: false,
+});
+
+if (result.error) {
+  if (result.error.code === 'ENOENT') {
+    process.stderr.write(
+      'openhuman binary not found. Try reinstalling: npm install -g openhuman\n'
+    );
+  } else {
+    process.stderr.write(`openhuman: ${result.error.message}\n`);
+  }
+  process.exit(1);
+}
+
+process.exit(result.status ?? 0);