feat(release): ship the embedded package runtime in every archive

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
     steps:
       - uses: actions/checkout@v7
       - uses: jdx/mise-action@v2
-      - run: bun install --frozen-lockfile
+      - run: bun install --frozen-lockfile --os='*' --cpu='*'
       - name: Derive native smoke matrix
         id: release-matrix
         shell: bash

.github/workflows/release.yml

@@ -58,7 +58,7 @@ jobs:
           test "$(git rev-parse HEAD)" = "$tag_commit"
           test "$(bun -p "require('./package.json').version")" = "$VERSION"
           echo "commit=$tag_commit" >> "$GITHUB_OUTPUT"
-      - run: bun install --frozen-lockfile
+      - run: bun install --frozen-lockfile --os='*' --cpu='*'
       - name: Derive native smoke matrix
         id: release-matrix
         shell: bash

AGENTS.md

@@ -1,12 +1,23 @@
 # Repository guidance
 
+## Learning more about Effect
+
+This repository uses the Effect Typescript library.
+
+Before writing any Effect code, first read `node_modules/effect/AGENTS.md`
+**completely**, and follow the links in the file when required.
+
+If you need to learn more about particular Effect apis and concepts that the
+guide doesn't cover, search through the source code in `node_modules/effect/src`.
+
 ## Release contract
 
 - `scripts/release.ts` is the source of truth for target IDs, Bun targets,
   archive names, executable names, SHA-256 files, and release manifests.
-- Every target must produce a one-executable archive, adjacent `.sha256`, an
-  entry in `checksums.txt`, and a native install smoke running `akua --version`,
-  `akua --help`, and `akua commands --limit 1`.
+- Every target must produce an archive containing the `akua` executable and its
+  adjacent target-native package runtime, an adjacent `.sha256`, an entry in
+  `checksums.txt`, and a native install smoke covering both cloud commands and a
+  real `akua pkg init` → `check` → `render` → `inspect` flow.
 - Keep the tested matrix aligned across the script and workflows: macOS
   arm64/x64, glibc Linux arm64/x64, and Windows x64. Use baseline Bun targets
   for Linux x64 and Windows x64.

README.md

@@ -13,8 +13,9 @@ The canonical executable is `akua`; there is no `cnap` compatibility binary.
 ## Install
 
 GitHub Releases and Homebrew are the supported install channels. Every GitHub
-archive contains one executable and has an adjacent SHA-256 file. A release also
-publishes `checksums.txt`, a complete release manifest, and the exact Homebrew
+archive contains the `akua` executable and its adjacent target-native package
+runtime, and has an adjacent SHA-256 file. A release also publishes
+`checksums.txt`, a complete release manifest, and the exact Homebrew
 artifact/checksum mapping.
 
 ### Homebrew
@@ -24,6 +25,7 @@ brew install akua-dev/tap/akua
 akua --version
 akua --help
 akua commands --limit 1
+akua pkg version
 ```
 
 Upgrade with:
@@ -61,12 +63,14 @@ if command -v sha256sum >/dev/null 2>&1; then
 else
   shasum -a 256 --check "${ASSET}.sha256"
 fi
-tar -xzf "$ASSET"
-mkdir -p "$HOME/.local/bin"
-install -m 0755 akua "$HOME/.local/bin/akua"
+INSTALL_ROOT="$HOME/.local/libexec/akua-v${VERSION}"
+mkdir -p "$INSTALL_ROOT" "$HOME/.local/bin"
+tar -xzf "$ASSET" -C "$INSTALL_ROOT"
+ln -sfn "$INSTALL_ROOT/akua" "$HOME/.local/bin/akua"
 "$HOME/.local/bin/akua" --version
 "$HOME/.local/bin/akua" --help
 "$HOME/.local/bin/akua" commands --limit 1
+"$HOME/.local/bin/akua" pkg version
 ```
 
 Ensure `~/.local/bin` is on `PATH`. Manual upgrades repeat these steps with a
@@ -88,11 +92,16 @@ $Expected = ((Get-Content "$Asset.sha256") -split "\s+")[0].ToLower()
 $Actual = (Get-FileHash $Asset -Algorithm SHA256).Hash.ToLower()
 if ($Actual -ne $Expected) { throw "SHA-256 mismatch for $Asset" }
 Expand-Archive $Asset -DestinationPath .\akua-release -Force
+$InstallRoot = "$HOME\libexec\akua-v$Version"
+New-Item -ItemType Directory -Force "$InstallRoot" | Out-Null
+Copy-Item .\akua-release\* "$InstallRoot" -Recurse -Force
 New-Item -ItemType Directory -Force "$HOME\bin" | Out-Null
-Copy-Item .\akua-release\akua.exe "$HOME\bin\akua.exe" -Force
+Copy-Item "$InstallRoot\akua.exe" "$HOME\bin\akua.exe" -Force
+Copy-Item "$InstallRoot\node_modules" "$HOME\bin\node_modules" -Recurse -Force
 & "$HOME\bin\akua.exe" --version
 & "$HOME\bin\akua.exe" --help
 & "$HOME\bin\akua.exe" commands --limit 1
+& "$HOME\bin\akua.exe" pkg version
 ```
 
 ### Supported release artifacts
@@ -108,7 +117,9 @@ Copy-Item .\akua-release\akua.exe "$HOME\bin\akua.exe" -Force
 Linux musl, Windows arm64, and other systems are not in the tested release
 contract. x64 Linux and Windows use Bun's baseline target for older CPUs. Unix
 archives preserve executable mode `0755`; the Windows ZIP contains `akua.exe`.
-The binaries are self-contained and do not require Bun to be installed.
+All archives also contain the target-native package runtime under
+`node_modules/@akua-dev`. Keep that directory adjacent to the executable. Bun is
+not required on the target machine.
 
 To audit a whole release, download `checksums.txt` plus the archives and run
 `sha256sum --check checksums.txt` on Linux or `shasum -a 256 --check

docs/architecture.md

@@ -266,8 +266,10 @@ published targets are:
 - `bun-linux-arm64` and `bun-linux-x64-baseline` (glibc);
 - `bun-windows-x64-baseline`.
 
-Each Unix `.tar.gz` contains only executable `akua` with mode `0755`; the
-Windows `.zip` contains only `akua.exe`. Stable names have the form
+Each archive contains executable `akua` (`akua.exe` on Windows) plus the
+target-native `@akua-dev/native` and `@akua-dev/native-engines` package runtime.
+The package runtime must stay adjacent to the executable under `node_modules`.
+Unix executables have mode `0755`. Stable names have the form
 `akua-v<version>-<os>-<arch>.<archive>`. Every archive has an adjacent
 `.sha256`, appears in `checksums.txt`, and is described in the release manifest.
 The generated Homebrew manifest maps the four macOS/Linux formula selectors to
@@ -277,8 +279,8 @@ exact release URLs and SHA-256 digests.
 release:package` cross-compiles and verifies the whole release directory, while
 `mise run release:smoke` extracts and executes the current host archive. CI
 builds the candidate once, then macOS arm64/x64, Linux arm64/x64, and Windows x64
-hosted runners execute `akua --version`, `akua --help`, and `akua commands
---limit 1` from their extracted archive.
+hosted runners exercise the cloud CLI and a real `akua pkg init` → `check` →
+`render` → `inspect` flow from their extracted archive.
 
 Release Please runs in manifest mode for the root Bun package. It uses
 `release-please-config.json` and `.release-please-manifest.json` to prepare

package.json

@@ -29,6 +29,7 @@
     "bun": ">=1.3.7"
   },
   "dependencies": {
+    "@akua-dev/sdk": "^0.9.4",
     "effect": "4.0.0-beta.106"
   },
   "patchedDependencies": {