release: v0.3.0

.github/workflows/ci.yml

@@ -169,6 +169,70 @@ jobs:
       - uses: Swatinem/rust-cache@v2
       - run: cargo build --release --workspace --all-features
 
+      # RFC-0110: validate the npm packaging path end-to-end on every PR using
+      # the just-built linux-x64 binary — assemble the packages, install them
+      # (--install-links copies like a registry install), and run the launcher.
+      # Catches packaging/launcher regressions without a real publish.
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+      - name: npm launcher unit tests
+        run: node --test
+        working-directory: npm/mycelium
+      # RFC-0111: SDK thin-wrapper. Unit tests are hermetic (injected spawn);
+      # the integration test then round-trips real JSON through the SDK using
+      # the release binary just built above, proving the --format json contract.
+      - name: SDK unit tests
+        run: node --test
+        working-directory: npm/sdk
+      - name: SDK integration test (against built binary)
+        run: node --test
+        working-directory: npm/sdk
+        env:
+          MYCELIUM_BIN: ${{ github.workspace }}/target/release/mycelium
+      - name: npm packaging smoke test (assemble → install → run)
+        run: |
+          set -euo pipefail
+          mkdir -p dist-bin/linux-x64
+          cp target/release/mycelium dist-bin/linux-x64/mycelium
+          node npm/scripts/build-npm.mjs --version 0.0.0-ci --bin-dir dist-bin --out dist-npm
+          mkdir -p smoke && cd smoke && npm init -y >/dev/null
+          npm install --install-links ../dist-npm/mycelium-linux-x64-gnu ../dist-npm/mycelium >/dev/null
+          OUT="$(node_modules/.bin/mycelium --version)"
+          echo "launcher output: $OUT"
+          echo "$OUT" | grep -qi mycelium
+      # RFC-0111: prove the assembled SDK resolves the prebuilt binary from its
+      # pinned optionalDependency (no MYCELIUM_BIN, no PATH) — the exact
+      # no-Cargo install path a fresh `npm i @aimasteracc/mycelium-sdk` takes.
+      - name: SDK packaging smoke test (assemble → install → resolve binary → query)
+        run: |
+          set -euo pipefail
+          mkdir -p sdk-smoke && cd sdk-smoke && npm init -y >/dev/null
+          npm install --install-links \
+            ../dist-npm/mycelium-linux-x64-gnu ../dist-npm/mycelium-sdk >/dev/null
+          node -e '
+            const { Mycelium } = require("@aimasteracc/mycelium-sdk");
+            const m = new Mycelium({ root: "." });
+            m.version().then((v) => {
+              console.log("sdk resolved binary →", v);
+              if (!/^mycelium /.test(v)) process.exit(1);
+            }).catch((e) => { console.error(e); process.exit(1); });
+          '
+      # RFC-0111 Phase 2: Python SDK (mycelium-rcig). Unit tests are hermetic
+      # (injected spawn, stdlib unittest — no pip install); the integration run
+      # round-trips real JSON through the SDK using the release binary above.
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - name: Python SDK unit tests
+        run: python -m unittest discover -s tests
+        working-directory: bindings/python
+      - name: Python SDK integration test (against built binary)
+        run: python -m unittest discover -s tests
+        working-directory: bindings/python
+        env:
+          MYCELIUM_BIN: ${{ github.workspace }}/target/release/mycelium
+
   doc-build:
     name: docs (rustdoc + mdbook)
     needs: [unit]
@@ -217,8 +281,13 @@ jobs:
           # --no-merges so historical PR merge commits (which never carried
           # sign-off and predate DCO enforcement) don't fail back-merge PRs
           # like release/* → develop. Authored commits must still sign off.
+          #
+          # Use full body grep instead of %(trailers:key=...) because GitHub
+          # squash-merge embeds Signed-off-by lines in the middle of the body
+          # (between individual commit entries) rather than as trailing lines,
+          # so the trailer parser misses them and false-fails those commits.
           for sha in $(git rev-list --no-merges ${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}); do
-            if ! git log -1 --format='%(trailers:key=Signed-off-by,valueonly)' $sha | grep -q .; then
+            if ! git log -1 --format='%B' "$sha" | grep -qiE '^Signed-off-by: .+ <.+>'; then
               echo "::error::Commit $sha lacks Signed-off-by trailer (DCO)."
               MISSING=$((MISSING+1))
             fi

.github/workflows/release.yml

@@ -61,9 +61,35 @@ jobs:
     needs: validate
     uses: ./.github/workflows/ci.yml
 
+  check-npm-token:
+    # Preflight (RFC-0110): warn when NPM_TOKEN is absent so the operator sees
+    # a clear diagnostic before the publish jobs run.  Graceful exit (no hard
+    # failure) so a missing token produces a SKIPPED npm publish rather than a
+    # failing release — crates.io and PyPI can still complete independently.
+    # Charter §5.12: every check must be SUCCESS or SKIPPED before merging
+    # release/* to main, so this job must never exit non-zero.
+    name: preflight (npm token present)
+    needs: validate
+    runs-on: ubuntu-latest
+    environment: npm
+    steps:
+      - name: Verify NPM_TOKEN is configured
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          if [ -z "${NPM_TOKEN:-}" ]; then
+            echo "::warning::NPM_TOKEN is not set in the 'npm' environment — npm publish will be skipped. Configure it in repo Settings → Environments → npm."
+          else
+            echo "NPM_TOKEN present."
+          fi
+
   publish-crates:
     name: publish to crates.io
-    needs: [validate, quality-recheck]
+    # Gate the first irreversible publish on the CLI binaries building
+    # successfully (RFC-0110 / Codex #519 P1): if any platform build fails we
+    # must NOT publish to a registry, or the release is partial (crates live but
+    # binaries missing). npm/pypi need publish-crates, so they are gated too.
+    needs: [validate, quality-recheck, build-cli-binaries]
     runs-on: ubuntu-latest
     timeout-minutes: 60
     environment: crates-io
@@ -145,50 +171,172 @@ jobs:
 
   publish-npm:
     name: publish to npm
-    needs: [validate, quality-recheck, publish-crates]
+    # RFC-0110: assemble the per-platform + launcher packages from the prebuilt
+    # binaries and publish them. needs build-cli-binaries for the artifacts.
+    needs: [validate, quality-recheck, publish-crates, build-cli-binaries]
     runs-on: ubuntu-latest
     timeout-minutes: 30
     environment: npm
     permissions:
       id-token: write  # for provenance
+    env:
+      VERSION: ${{ needs.validate.outputs.version }}
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
         with:
           node-version: '20'
           registry-url: 'https://registry.npmjs.org'
-      - run: |
-          if [ -d "bindings/node" ]; then
-            cd bindings/node
-            npm ci
-            npm publish --access public --provenance
-          else
-            echo "no bindings/node yet — skipping"
-          fi
+      - name: Download CLI binaries
+        uses: actions/download-artifact@v7
+        with:
+          pattern: cli-*
+          path: dl
+      - name: Reshape artifacts into a platform-keyed bin dir
+        run: |
+          mkdir -p dist-bin
+          for d in dl/cli-*; do
+            key="${d#dl/cli-}"
+            mkdir -p "dist-bin/$key"
+            cp "$d"/* "dist-bin/$key/"
+          done
+          ls -R dist-bin
+      - name: Assemble npm packages
+        run: node npm/scripts/build-npm.mjs --version "$VERSION" --bin-dir dist-bin --out dist-npm
+      - name: Publish packages (idempotent — platform packages first)
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          if [ -z "${NODE_AUTH_TOKEN:-}" ]; then
+            echo "::warning::NPM_TOKEN is not set — skipping npm publish. Configure it in repo Settings → Environments → npm."
+            exit 0
+          fi
+          publish_one() {
+            dir="$1"
+            name=$(node -p "require('./$dir/package.json').name")
+            ver=$(node -p "require('./$dir/package.json').version")
+            if npm view "$name@$ver" version >/dev/null 2>&1; then
+              echo "$name@$ver already on npm; skipping"
+              return 0
+            fi
+            if ! ( cd "$dir" && npm publish --access public --provenance ) 2>/tmp/npm_pub_err.log; then
+              # Issue #534: the @aimasteracc scope is registered and NPM_TOKEN
+              # authenticates (npm whoami -> aimasteracc), so ANY publish failure
+              # is a real error — fail the release loudly. The prior E404
+              # graceful-skip (PR #533) masked a non-authenticating token and
+              # produced false-green releases (the v0.2.0 saga). Never again.
+              cat /tmp/npm_pub_err.log >&2
+              return 1
+            fi
+          }
+          # Platform packages must exist before the main package and the SDK
+          # (whose optionalDependencies reference them). The SDK is published
+          # explicitly after the main package, so skip it in the platform glob.
+          for dir in dist-npm/mycelium-*; do
+            [ -d "$dir" ] || continue
+            [ "$dir" = "dist-npm/mycelium-sdk" ] && continue
+            publish_one "$dir"
+          done
+          publish_one "dist-npm/mycelium"
+          # RFC-0111: thin-CLI-wrapper SDK, published from the same release.
+          publish_one "dist-npm/mycelium-sdk"
 
   publish-pypi:
     name: publish to PyPI
-    needs: [validate, quality-recheck, publish-crates]
+    # GITFLOW registry order is crates.io → npm → PyPI: depend on publish-npm so
+    # a failed/incomplete npm release blocks PyPI (no partial registry release).
+    needs: [validate, quality-recheck, publish-crates, publish-npm]
     runs-on: ubuntu-latest
     timeout-minutes: 30
     environment: pypi
     permissions:
       id-token: write  # for Trusted Publishers
+    env:
+      VERSION: ${{ needs.validate.outputs.version }}
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-python@v6
         with:
           python-version: '3.12'
-      - run: |
-          if [ -d "bindings/python" ]; then
-            pip install maturin
-            cd bindings/python
-            maturin publish
-          else
+      # RFC-0111 Phase 2: the Python SDK (mycelium-rcig) is a pure-Python thin
+      # CLI wrapper — built with the standard `build` backend, not maturin
+      # (there is no Rust extension). The version is pinned to the release
+      # version; publishing is idempotent via skip-existing.
+      - name: Build the pure-Python SDK wheel
+        id: build
+        run: |
+          set -euo pipefail
+          if [ ! -d "bindings/python" ]; then
             echo "no bindings/python yet — skipping"
+            echo "built=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          cd bindings/python
+          sed -i -E "s/^version = \".*\"/version = \"$VERSION\"/" pyproject.toml
+          sed -i -E "s/^__version__ = \".*\"/__version__ = \"$VERSION\"/" mycelium_rcig/__init__.py
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI (Trusted Publishers, idempotent)
+        if: steps.build.outputs.built != 'false'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: bindings/python/dist
+          skip-existing: true
+
+  build-cli-binaries:
+    # RFC-0110: cross-compile the `mycelium` CLI for each distributed platform,
+    # upload each as a workflow artifact (consumed by publish-npm in a follow-up
+    # and attached to the GitHub Release below). Native builds for 4 targets;
+    # `cross` handles the linux-arm64 C toolchain (tree-sitter grammars are C).
+    name: build CLI binary (${{ matrix.key }})
+    needs: [validate, quality-recheck]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        # Both macOS targets build on macos-14 (arm64, plentiful runners): arm64
+        # natively, x86_64 by cross-compiling with the universal Apple toolchain
+        # (`cargo build --target x86_64-apple-darwin` — verified locally to
+        # produce an x86_64 Mach-O incl. tree-sitter C). Avoids the deprecated /
+        # scarce macos-13 (Intel) runner queue that stalled the release ~20min.
+        include:
+          - { key: darwin-arm64, os: macos-14,        target: aarch64-apple-darwin,      exe: mycelium,     cross: false }
+          - { key: darwin-x64,   os: macos-14,        target: x86_64-apple-darwin,       exe: mycelium,     cross: false }
+          - { key: linux-x64,    os: ubuntu-latest,   target: x86_64-unknown-linux-gnu,  exe: mycelium,     cross: false }
+          - { key: linux-arm64,  os: ubuntu-latest,   target: aarch64-unknown-linux-gnu, exe: mycelium,     cross: true  }
+          - { key: win32-x64,    os: windows-latest,  target: x86_64-pc-windows-msvc,    exe: mycelium.exe, cross: false }
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: release-${{ matrix.target }}
+      - name: Install cross (linux-arm64)
+        if: ${{ matrix.cross }}
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cross
+      - name: Build release binary
+        shell: bash
+        run: |
+          if [ "${{ matrix.cross }}" = "true" ]; then
+            cross build --release -p mycelium-rcig-cli --target ${{ matrix.target }}
+          else
+            cargo build --release -p mycelium-rcig-cli --target ${{ matrix.target }}
           fi
+      - name: Stage binary under its platform key
+        shell: bash
+        run: |
+          mkdir -p "dist-bin/${{ matrix.key }}"
+          cp "target/${{ matrix.target }}/release/${{ matrix.exe }}" "dist-bin/${{ matrix.key }}/${{ matrix.exe }}"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: cli-${{ matrix.key }}
+          path: dist-bin/${{ matrix.key }}/${{ matrix.exe }}
+          if-no-files-found: error
 
   finalize:
     name: merge to main, tag, GitHub Release
@@ -198,7 +346,7 @@ jobs:
     # (scripts/release-ceremony.sh) or a manual workflow_dispatch serves as
     # the explicit human authorization step.
     if: github.event_name == 'workflow_dispatch'
-    needs: [validate, publish-crates, publish-npm, publish-pypi]
+    needs: [validate, publish-crates, publish-npm, publish-pypi, build-cli-binaries]
     runs-on: ubuntu-latest
     timeout-minutes: 15
     permissions:
@@ -263,13 +411,38 @@ jobs:
           git tag -a "v$VERSION" -m "Release v$VERSION"
           git push origin "v$VERSION"
 
-      # Step D — Create the GitHub Release on the tag reachable from main.
+      # Step D — Download the per-platform CLI binaries and rename them with a
+      # platform suffix (the raw artifacts are all named `mycelium`/`.exe`, which
+      # would collide as release assets). RFC-0110.
+      - name: Download CLI binaries
+        uses: actions/download-artifact@v7
+        with:
+          pattern: cli-*
+          path: dist-release
+      - name: Collect release assets
+        shell: bash
+        run: |
+          mkdir -p release-assets
+          for d in dist-release/cli-*; do
+            key="${d#dist-release/cli-}"
+            if [ -f "$d/mycelium.exe" ]; then
+              cp "$d/mycelium.exe" "release-assets/mycelium-$key.exe"
+            elif [ -f "$d/mycelium" ]; then
+              cp "$d/mycelium" "release-assets/mycelium-$key"
+            fi
+          done
+          ls -la release-assets
+
+      # Step E — Create the GitHub Release on the tag reachable from main,
+      # attaching the per-platform binaries (a download path for users who do
+      # not use npm/bun/cargo).
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v3
         with:
           tag_name: v${{ env.VERSION }}
           generate_release_notes: true
           target_commitish: main
+          files: release-assets/*
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

.gitignore

@@ -4,6 +4,11 @@
 **/*.rs.bk
 Cargo.lock.bak
 
+# npm distribution build artifacts (RFC-0110) — assembled in CI, never committed
+/dist-bin/
+/dist-npm/
+node_modules/
+
 # IDE
 /.idea/
 /.vscode/*