@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/.github/workflows/docs.yml

@@ -0,0 +1,265 @@
+name: Deploy Docs
+
+# The 4.x line's docs deploy, from main. A Pages deploy replaces the whole
+# site, so each deploy carries every line (scripts/assemble-docs-site.mjs):
+#
+# - /v4/ built from this commit, as pages that send each reader to the same
+#   page at https://b3pay.net/docs/ic-reactor/, where b3pay-site.yml publishes
+#   the 4.x docs (--v4-moved-to), with the build's Markdown copies and
+#   llms.txt beside them;
+# - /v3/ rebuilt from the v3 branch on every deploy, with v3's llms.txt and
+#   llms-full.txt beside it (option A of the 4.0 GA flip; the owner's to
+#   overturn). The v3 branch has no docs deploy of its own. A 3.x docs build
+#   that fails blocks the deploy: fix it on v3, or switch to option B;
+# - /v2/, the static 2.x site kept from gh-pages;
+# - /candid-core/, Candid Core's site, built from B3Pay/Meant's main
+#   with its own generator (`node website/build.mjs`, Node built-ins only),
+#   in a job of its own (`candid-core-site`), as pages that send each reader
+#   to the same page at https://b3pay.net/docs/meant/, where B3Pay/Meant
+#   publishes it (--candid-core-moved-to). The build names the pages, and the
+#   link check below checks the 4.x pages' links into it. A page added to
+#   that repository's site gets its page here at the next deploy: the daily
+#   run below, or a dispatch. A generator that fails on that main stops the
+#   deploy; a dispatch with `candid-core-ref` set to a commit that builds
+#   publishes in the meantime;
+# - the root: / goes to https://b3pay.net/docs/ic-reactor/, the 404 page
+#   sends a miss to its line's home or to /v4/, /llms.txt is the 4.x guide
+#   (packages/core/llms.txt), and /llms-full.txt stays the frozen 3.x file.
+#
+# The 3.x and 2.x docs stay here (the owner's call, 2026-10-31). Before it
+# publishes, the build checks that b3pay.net serves IC Reactor's docs, with
+# the API reference, and Meant's.
+#
+# Option B, a static /v3/ snapshot: commit one 3.x build to gh-pages:v3/
+# (with Pages' source set to GitHub Actions first, or that push starts a
+# legacy Pages build that replaces the site), delete the two v3 steps below,
+# drop --v3-line from the assembly step, and point --root-llms-full at
+# existing-pages/v3/llms-full.txt (or drop it to serve no /llms-full.txt). The
+# assembly then keeps gh-pages' /v3/ and refuses to publish without one.
+#
+# A push to v3 deploys nothing: after a 3.x docs fix, run this workflow by hand
+# on main (workflow_dispatch) to republish /v3/.
+#
+# Deploying from main needs main in the github-pages environment's deployment
+# branch policy (repo settings).
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "packages/**"
+      - ".github/workflows/docs.yml"
+      - "scripts/assemble-docs-site.mjs"
+  # Picks up Candid Core's site, which changes in another repository.
+  schedule:
+    - cron: "23 5 * * *"
+  workflow_dispatch:
+    inputs:
+      candid-core-ref:
+        description: "The B3Pay/Meant ref whose pages /candid-core/ sends on to b3pay.net"
+        type: string
+        default: main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Candid Core's site. The generator is another repository's code, so it runs
+  # here rather than in `build`: it never sees this repository's tree, its
+  # pnpm cache or the Pages artifact, and only its output (website/dist) is
+  # handed on. Node is the version Candid Core's own docs workflow builds with.
+  candid-core-site:
+    name: Build Candid Core's site
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out Candid Core
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          repository: B3Pay/Meant
+          ref: ${{ inputs.candid-core-ref || 'main' }}
+          persist-credentials: false
+
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: "24.18.0"
+
+      # The site generator takes no dependency, so no install. The commit goes
+      # to the run's summary: main moves, and the deploy should say what it
+      # published.
+      - name: Build
+        run: |
+          set -euo pipefail
+          node website/build.mjs
+          echo "Candid Core's pages at /candid-core/, sent on to b3pay.net, are those of B3Pay/Meant@$(git rev-parse HEAD)." >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Hand the site on
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: candid-core-site
+          path: website/dist
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 7
+
+  build:
+    name: Build Documentation
+    needs: candid-core-site
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: 22
+
+      - name: Setup pnpm
+        run: |
+          corepack enable
+          corepack prepare pnpm@10.30.3 --activate
+          pnpm --version
+
+      - name: Get pnpm store path
+        id: pnpm-store
+        run: echo "path=$(pnpm store path)" >> "$GITHUB_OUTPUT"
+
+      - name: Cache pnpm store
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+        with:
+          path: ${{ steps.pnpm-store.outputs.path }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build documentation (Astro)
+        run: pnpm docs:build
+
+      - name: Download Candid Core's site
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: candid-core-site
+          path: candid-core-site
+
+      # Advisory on a push or a dispatch, not blocking: `deploy` has
+      # `needs: build`, so failing would stop the site updating at all rather
+      # than publishing one dead link. The PR gate in docs-check.yml is the
+      # hard one. The daily run is the exception: it is unattended and brings
+      # only Candid Core's and the 3.x line's changes, so a dead link there
+      # fails the run and leaves the live site as it was.
+      - name: Check links
+        continue-on-error: ${{ github.event_name != 'schedule' }}
+        env:
+          CANDID_CORE_SITE: ${{ github.workspace }}/candid-core-site
+        run: pnpm docs:check-links
+
+      # docs/dist should be Astro static output
+
+      # The 3.x docs, rebuilt from the v3 branch on every deploy (option A), so
+      # a deploy republishes /v3/ instead of dropping it.
+      - name: Check out the 3.x line (v3)
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: v3
+          path: v3-line
+
+      - name: Build the 3.x documentation
+        working-directory: v3-line
+        run: |
+          set -euo pipefail
+          pnpm install --frozen-lockfile --filter '!./examples/**'
+          pnpm docs:build
+
+      - name: Download existing Pages content
+        id: existing-pages
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: gh-pages
+          path: existing-pages
+        # gh-pages does not exist on the very first deploy. A failure here is only
+        # tolerable in that case; the guard below turns any other failure into an error
+        # instead of silently publishing a site whose /v2 URLs all 404.
+        continue-on-error: true
+
+      # b3pay.net must serve the docs /v4/ and /candid-core/ send readers to.
+      # When its IC Reactor home, an API reference page or its Meant home is
+      # missing, the deploy stops and the live site stays as it was. The API
+      # reference is what b3pay.net gets only from the module this
+      # repository publishes, not from the copy it pinned before.
+      - name: Check that b3pay.net serves the moved docs
+        run: |
+          set -euo pipefail
+          # The page is read whole before it is searched: piped into
+          # `grep -q`, which stops at the title, curl fails on the rest of a
+          # page longer than the pipe holds, and pipefail fails the check.
+          check() {
+            if ! page=$(curl -fsSL --retry 3 --max-time 30 "$1"); then
+              echo "::error::$1 could not be read"
+              exit 1
+            fi
+            if ! grep -q "$2" <<<"$page"; then
+              echo "::error::$1 does not serve a page with $2"
+              exit 1
+            fi
+          }
+          check https://b3pay.net/docs/ic-reactor/ "<title>[^<]*IC Reactor"
+          check https://b3pay.net/docs/ic-reactor/libs/functions/createclient/ "<title>createClient"
+          check https://b3pay.net/docs/meant/ "<title>Meant</title>"
+
+      - name: Merge existing + new docs
+        run: |
+          set -euo pipefail
+          if [ ! -d "existing-pages" ] && git ls-remote --exit-code --heads origin gh-pages >/dev/null 2>&1; then
+            echo "::error::gh-pages exists remotely but could not be checked out." \
+                 "Refusing to publish, which would drop every previously published version."
+            exit 1
+          fi
+          node scripts/assemble-docs-site.mjs \
+            --out final-docs \
+            --existing existing-pages \
+            --v4 docs/dist \
+            --v3-line v3-line \
+            --candid-core candid-core-site \
+            --root-llms packages/core/llms.txt \
+            --root-llms-full v3-line/llms-full.txt \
+            --cname CNAME \
+            --v4-moved-to https://b3pay.net/docs/ic-reactor/ \
+            --candid-core-moved-to https://b3pay.net/docs/meant/
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
+        with:
+          path: final-docs
+
+  deploy:
+    name: Deploy
+    needs: build
+    runs-on: ubuntu-latest
+    # The only job that needs the Pages OIDC token; its sole step is
+    # actions/deploy-pages.
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5

package/.github/workflows/e2e.yml

@@ -0,0 +1,90 @@
+name: E2E Tests
+
+on:
+  # main is the 4.x line. See ci.yml.
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+env:
+  # Pinned so a compromised release cannot run its install script in CI, and so a
+  # regression is traceable to a version. Bump deliberately.
+  ICP_CLI_VERSION: 1.2.0
+  IC_WASM_VERSION: 0.11.1
+
+jobs:
+  e2e:
+    name: E2E Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: 22
+
+      - name: Setup pnpm
+        run: |
+          corepack enable
+          corepack prepare pnpm@10.30.3 --activate
+          pnpm --version
+
+      - name: Get pnpm store path
+        id: pnpm-store
+        run: echo "path=$(pnpm store path)" >> "$GITHUB_OUTPUT"
+
+      - name: Cache pnpm store
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
+        with:
+          path: ${{ steps.pnpm-store.outputs.path }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      # icp deploy builds the Rust hello_actor canister (e2e/icp.yaml).
+      - name: Setup Rust for the hello_actor canister build
+        uses: ./.github/actions/setup-rust-wasm
+
+      # e2e/package.json pins the same two versions as devDependencies, and
+      # e2e/test.sh puts e2e/node_modules/.bin first on PATH, so the suite runs
+      # those copies, here as locally. The global install is a fallback only.
+      # The next step fails when the two drift, so bump both places together.
+      - name: Install icp-cli and ic-wasm
+        run: npm install -g @icp-sdk/icp-cli@${{ env.ICP_CLI_VERSION }} @icp-sdk/ic-wasm@${{ env.IC_WASM_VERSION }}
+
+      - name: Confirm the global tools match e2e/package.json
+        run: |
+          check() {
+            pinned="$(node -p "require('./e2e/package.json').devDependencies['$1']")"
+            actual="$($2 --version | awk '{ print $2 }')"
+            echo "$2 $actual (e2e/package.json pins $pinned)"
+            if [ "$actual" != "$pinned" ]; then
+              echo "::error::the global $2 is $actual, but e2e/package.json pins $1 $pinned. Bump ICP_CLI_VERSION / IC_WASM_VERSION and e2e/package.json together."
+              exit 1
+            fi
+          }
+          check @icp-sdk/icp-cli icp
+          check @icp-sdk/ic-wasm ic-wasm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build packages
+        run: pnpm build
+
+      - name: Run e2e tests
+        run: |
+          cd e2e
+          bash ./test.sh

package/.github/workflows/examples-published.yml

@@ -0,0 +1,97 @@
+name: Examples on the published packages
+
+# The examples job of CI runs the examples inside the workspace, linked to the
+# packages built from the branch. This runs each of them as someone who copies
+# it out of the repository does, and as StackBlitz does: its tracked files in a
+# directory outside the checkout, a plain `npm install` from the registry, the
+# @ic-reactor/* packages at the version one npm dist-tag names, then its
+# typecheck, test and build scripts and the start command of its
+# .stackblitzrc, that one under a model of what StackBlitz's WebContainer
+# lacks (scripts/test-examples-published.mjs).
+#
+# The dist-tag: with wait-for (the release's run), the one that release
+# publishes under, `beta` for a prerelease tag and `latest` for a stable one;
+# without it (push, pull request, weekly and manual runs), the one of the
+# version in packages/core/package.json, the branch's last release, to whose
+# exact version release.js syncs the examples: `latest` after 4.0.0, `beta`
+# through a later prerelease cycle such as 4.1.0's.
+#
+# On pull requests to main that touch an example or this check, so a change
+# that makes an example use an API the published packages lack fails here.
+# That is intended: such an example change lands with the release that
+# publishes the API, not before it. A release PR, and the push that merges it,
+# sync every example to the branch's own version before it is published; a run
+# without wait-for that finds exactly that (every @ic-reactor/* range is
+# ^<the version in packages/core/package.json>, and npm has no such version
+# yet) defers and passes, saying so (awaitsRelease), unless a dependency uses
+# a local protocol (workspace:, file: …); the checks that need no registry
+# (staticFindings) still run first and fail it. Once that version is
+# published, the same run tests the examples against its dist-tag. Any other
+# unsatisfied range still fails, so this is not a required check. The run that
+# counts for a release is the one release.yml calls after its publish job
+# (workflow_call), with --wait-for the tag's version, so it tests the tagged
+# examples against the packages just published. A PR touching only packages/
+# or docs/ cannot change the outcome (the script installs the published
+# packages, not the branch's), so it does not run this; every push to main
+# does, so a breaking release of Vite, Next, TanStack Query or another range
+# still shows up within a push. Weekly, because those ranges resolve to new
+# releases with no commit of ours. GitHub runs `schedule` and offers
+# `workflow_dispatch` only for workflow files on the default branch, main.
+# The paths filter and the triggers are the owner's call.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+    paths:
+      - "examples/**"
+      - "scripts/test-examples-published.mjs"
+      - "scripts/test-examples-published.test.mjs"
+      - "scripts/example-projects.js"
+      - ".github/workflows/examples-published.yml"
+  workflow_dispatch:
+  workflow_call:
+    inputs:
+      wait-for:
+        description: The version (or its tag) whose release the run tests. The dist-tag that release publishes under (beta for a prerelease, latest for a stable version) of core and of every @ic-reactor package the examples declare must name it, with its integrity and its tarball served, before the run starts (a leading v is dropped)
+        type: string
+        required: false
+        default: ""
+  schedule:
+    # Mondays, 06:17 UTC.
+    - cron: "17 6 * * 1"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  examples-published:
+    name: Examples on the published packages
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      # The examples need Node 22.18 or later (node-agent-tool runs its .ts
+      # files with Node's type stripping); 22 resolves to the newest 22.x.
+      # The npm cache holds tarballs by integrity, and the script compares
+      # each @ic-reactor/* package's integrity with the registry's, so a cached
+      # tarball proves the same as a downloaded one.
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: examples/*/package.json
+
+      # No `pnpm install`: the script needs only Node, npm and git, and the
+      # examples get nothing from the workspace.
+      - name: Test the examples against the published packages
+        env:
+          WAIT_FOR: ${{ inputs.wait-for }}
+        run: node scripts/test-examples-published.mjs ${WAIT_FOR:+--wait-for "$WAIT_FOR"}