ci.yml

name: CI

on:
  push:
    branches: [master]
  pull_request:
  workflow_dispatch:
  # Release calls these same jobs before publishing. `needs` cannot depend on
  # jobs in a separate workflow.
  workflow_call:

# These jobs need read access only. Each checkout also disables persisted
# credentials so later steps cannot read the workflow token from `.git/config`.
permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  NODE_VERSION: '22'
  # Keep this version in sync with the Foundry image digest in
  # docker/chain.Dockerfile. A floating `nightly` would change test inputs.
  FOUNDRY_VERSION: 'v1.7.1'
  # The Solana E2E starts solana-test-validator. The Agave release is pinned by
  # version and by the SHA-256 GitHub records for the Linux archive.
  AGAVE_VERSION: 'v4.1.1'
  AGAVE_SHA256: 'a5c8e74b8ffa9ce906872b812849057c7fb21cf036ba08f219eb335e20fa4fb3'
  # NEAR E2E tests use nearcore's sandbox. No archive digest is published;
  # this SHA-256 was recorded when the version was pinned.
  NEAR_SANDBOX_VERSION: '2.13.4'
  NEAR_SANDBOX_SHA256: '5690a4635172263cf026683f75965cac09dd916912584f12709974fed620163f'

jobs:
  quality:
    name: Lint and typecheck
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
        with:
          persist-credentials: false
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm
      - run: npm ci
      # Compare exported public types with the checked-in contract baseline.
      - run: npm run check:contract
      - run: npm run lint
      - run: npm run typecheck

  test:
    name: Unit and integration tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
        with:
          persist-credentials: false
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm
      # The local-chain tests start Anvil. Without Foundry they skip locally
      # but fail in CI.
      - uses: foundry-rs/foundry-toolchain@908c540300062bd5a7e473851cdb4282204cee09 # v1.9.1
        with:
          version: ${{ env.FOUNDRY_VERSION }}
      - run: npm ci
      - run: npm run test:coverage
      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        if: always()
        with:
          name: coverage
          path: coverage/
          retention-days: 7

  contracts:
    name: Solidity contracts
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
        with:
          persist-credentials: false
      - uses: foundry-rs/foundry-toolchain@908c540300062bd5a7e473851cdb4282204cee09 # v1.9.1
        with:
          version: ${{ env.FOUNDRY_VERSION }}
      - run: forge build
        working-directory: contracts
      - run: forge test -vv
        working-directory: contracts

  e2e:
    name: Deterministic E2E
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
        with:
          persist-credentials: false
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm
      - uses: foundry-rs/foundry-toolchain@908c540300062bd5a7e473851cdb4282204cee09 # v1.9.1
        with:
          version: ${{ env.FOUNDRY_VERSION }}
      - name: Install the Agave CLI
        run: |
          archive="$RUNNER_TEMP/agave.tar.bz2"
          curl -sSfL -o "$archive" \
            "https://github.com/anza-xyz/agave/releases/download/${AGAVE_VERSION}/solana-release-x86_64-unknown-linux-gnu.tar.bz2"
          echo "${AGAVE_SHA256}  $archive" | sha256sum -c -
          tar -xjf "$archive" -C "$RUNNER_TEMP"
          echo "$RUNNER_TEMP/solana-release/bin" >> "$GITHUB_PATH"
      - name: Install the NEAR sandbox
        run: |
          archive="$RUNNER_TEMP/near-sandbox.tar.gz"
          curl -sSfL -o "$archive" \
            "https://s3-us-west-1.amazonaws.com/build.nearprotocol.com/nearcore/Linux-x86_64/${NEAR_SANDBOX_VERSION}/near-sandbox.tar.gz"
          echo "${NEAR_SANDBOX_SHA256}  $archive" | sha256sum -c -
          tar -xzf "$archive" -C "$RUNNER_TEMP"
          echo "$RUNNER_TEMP/Linux-x86_64" >> "$GITHUB_PATH"
      - run: npm ci
      # Tests run Anvil, solana-test-validator and the NEAR sandbox locally,
      # with deployed or preloaded tokens and no public RPC or facilitator.
      - run: npm run test:e2e

  package:
    name: npm package
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
        with:
          persist-credentials: false
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm
      - run: npm ci
      # Check repository, bug-report and homepage URLs before packaging so
      # npm's vulnerability-report link points to this repository.
      - name: Verify package provenance metadata
        run: node scripts/check-package-metadata.mjs

      - run: npm run build
      # Exercise the built CLI separately from tests that run source files.
      - run: npm run test:cli:dist
      - run: npx vitest run tests/unit/cli/packaging.test.ts
      # Install the tarball outside the repository. First check the CLI and
      # `createGateway` without optional peers. A stray `viem` import can break
      # startup even when in-repo tests pass because peers are installed here.
      # Then install peers and check that the subpaths work with the main entry.
      - name: Install package without optional peers
        run: |
          TARBALL="$(npm pack --silent | tail -1)"
          mkdir -p "$RUNNER_TEMP/bare" && cd "$RUNNER_TEMP/bare"
          npm init -y >/dev/null
          npm install "$GITHUB_WORKSPACE/$TARBALL"
          # Read peers from the manifest so newly declared peers are checked
          for peer in $(node -p "Object.keys(require('$GITHUB_WORKSPACE/package.json').peerDependencies).join(' ')"); do
            if [ -d "node_modules/$peer" ]; then
              echo "optional peer $peer was installed by default, so the split is not working"
              exit 1
            fi
          done
          npx agent-commerce --help
          npx agent-commerce --version
          npx agent-commerce version | grep -q '@modelcontextprotocol/server'
          npx agent-commerce init --yes
          npx agent-commerce validate
          # `start` loads each enabled feature's peers, so the init config,
          # which enables x402, must refuse and name the missing package
          status=0
          timeout 30 npx agent-commerce start > start.log 2>&1 || status=$?
          cat start.log
          test "$status" -eq 1
          grep -q 'payments.x402 is enabled, but the package' start.log
          # Peers load before the receipt store opens. Nothing was created
          test ! -e data/receipts.db
          # Free HTTP needs no peers with MCP, AP2 and payment rails disabled
          cat > free.yaml <<'EOF'
          version: 1
          merchant: { id: free, name: Free, publicBaseUrl: "http://localhost:8081" }
          server: { port: 8081, host: 127.0.0.1 }
          storage: { receipts: { driver: sqlite, path: ./free.sqlite } }
          protocols: { http: { enabled: true }, mcp: { enabled: false, mountPath: /mcp } }
          resources:
            hello:
              name: Hello
              input: { type: object, properties: {}, additionalProperties: false }
              backend: { type: http, method: GET, url: "http://127.0.0.1:3000/hello" }
              pricing: { type: free }
              expose: [http]
          payments: {}
          EOF
          ./node_modules/.bin/agent-commerce start --config free.yaml &
          pid=$!
          for _ in $(seq 30); do
            node -e "fetch('http://127.0.0.1:8081/health').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))" && break
            sleep 1
          done
          node -e "fetch('http://127.0.0.1:8081/health').then((r) => { if (!r.ok) process.exit(1); })"
          kill -TERM "$pid"
          wait "$pid"
          # The main entry must compose and serve without optional peers
          node --input-type=module -e "
            import { createGateway, loadConfig, receipts } from '@devlab.group/agent-commerce';
            const loaded = await loadConfig({ path: 'config.yaml' });
            const config = { ...loaded, protocols: { ...loaded.protocols, mcp: { ...loaded.protocols.mcp, enabled: false } } };
            const gateway = await createGateway({
              config,
              store: receipts({ path: ':memory:' }),
              paymentProviders: [],
              protocolAdapters: [],
            });
            const { url } = await gateway.listen();
            const health = await fetch(url + '/health');
            if (!health.ok) throw new Error('GET /health -> ' + health.status);
            await gateway.close();
            console.log('bare install ok: gateway composed, served and closed');
          "

      - name: Install package with optional peers
        run: |
          cd "$RUNNER_TEMP/bare"
          npm install @modelcontextprotocol/server@2.3.0 @x402/core@2.25.0 @x402/evm@2.25.0 viem@2.57.1
          node --input-type=module -e "
            import { createGateway, loadConfig, receipts, CommerceError } from '@devlab.group/agent-commerce';
            import { mcp } from '@devlab.group/agent-commerce/mcp';
            import { x402 } from '@devlab.group/agent-commerce/x402';
            const config = await loadConfig({ path: 'config.yaml' });
            const gateway = await createGateway({
              config,
              store: receipts({ path: ':memory:' }),
              paymentProviders: [],
              protocolAdapters: [mcp({ mountPath: config.protocols.mcp.mountPath })],
            });
            const { url } = await gateway.listen();
            const tools = await fetch(url + config.protocols.mcp.mountPath, {
              method: 'POST',
              headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream' },
              body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} }),
            });
            if (!tools.ok) throw new Error('tools/list -> ' + tools.status);
            await gateway.close();
            // Subpaths must share CommerceError with the main entry; separate
            // bundled copies would fail the instanceof check.
            let caught;
            try { x402({ asset: 'nope', payTo: '0x0', network: 'eip155:31337' }); } catch (e) { caught = e; }
            if (!(caught instanceof CommerceError)) throw new Error('CommerceError identity broken across subpaths');
            console.log('subpath install ok: mcp + x402 compose with the main entry');
          "
          # With its peers installed, `start` serves the init config's paid
          # resource: a 402 challenge, which needs no chain
          ./node_modules/.bin/agent-commerce start &
          pid=$!
          for _ in $(seq 30); do
            node -e "fetch('http://127.0.0.1:8080/health').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))" && break
            sleep 1
          done
          node -e "
            fetch('http://127.0.0.1:8080/api/resources/report/invoke', {
              method: 'POST',
              headers: { 'content-type': 'application/json' },
              body: '{}',
            }).then((r) => {
              if (r.status !== 402 || !r.headers.has('payment-required')) {
                console.error('invoke -> ' + r.status);
                process.exit(1);
              }
              console.log('start ok: paid resource challenged with 402');
            });
          "
          kill -TERM "$pid"
          wait "$pid"

  build:
    name: Build and quickstart test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
        with:
          persist-credentials: false
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm
      - run: npm ci
      - run: npm run build
      # Run the README quickstart without installing Foundry on the runner.
      # Docker starts the local chain; chain-deploy uses the committed MockUSDC
      # artifact. `doctor` and the demo agent check the running stack.
      - name: Run README quickstart
        run: |
          # Match the runner's UID/GID so chain-deploy can write the host-mounted
          # .deploy/local.json manifest
          export DOCKER_UID="$(id -u)" DOCKER_GID="$(id -g)"
          docker compose up -d --build
          npm run agent-commerce -- doctor --config config-demo.yaml
          npm run demo:agent
      - name: Compose logs on failure
        if: failure()
        run: docker compose logs
      - name: Tear down
        if: always()
        run: docker compose down -v