@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,430 @@
+name: CI
+
+on:
+  # main is the 4.x line. The 3.x line (v3) runs its own copy of this file: a
+  # run uses the workflow file of its own ref.
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  # Only collapse runs for the same pull request. Keying on github.ref made every
+  # push to main share one group, so back-to-back merges cancelled each other and
+  # left commits on main with no completed CI run.
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint-and-typecheck:
+    name: Lint & Type Check
+    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-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --filter '!./examples/**'
+
+      - name: Format check
+        run: pnpm format:check
+
+      - name: AI context check
+        run: pnpm check:ai-context
+
+      # stack.json names the Meant release this branch is tested against.
+      # Each Meant pin in a tracked package.json, each
+      # `@meantjs/<name>@<version>` in a package.json value or a .md, .mdx
+      # or .txt file, each docs peer-table row and the two pins in code must
+      # be exactly that version, outside the changelogs and the frozen paths;
+      # each listed package must be pinned somewhere. A repin changes
+      # stack.json and runs `pnpm sync:stack` (CONTRIBUTING.md, "The Meant
+      # pins").
+      - name: Stack pins
+        run: pnpm check:stack
+
+      - name: Build packages
+        run: pnpm build
+
+      # The public surface is the plan in scripts/export-budget.mjs and no
+      # more: it reads the declarations just built and fails on a name the
+      # plan does not list, on more names than an entry's cap, on a name two
+      # entries export, on a name @meantjs/schema or TanStack Query
+      # already exports (D35: one import path per name), and on an `exports`
+      # subpath or a publishable package the plan has no entry for.
+      - name: Export budget
+        run: pnpm check:exports
+
+      # Compiles every ts/tsx fence of the AI guides, the skills and the
+      # READMEs against the declarations just built, the API an agent in a
+      # consumer project pastes them against. check:ai-context keeps their
+      # versions and links current but compiles nothing. Every file of
+      # scripts/ai-context-files.js is in its set, so a guide is compiled the
+      # commit it lands.
+      - name: Snippet check
+        run: pnpm check:snippets
+
+      - name: Type check
+        run: pnpm typecheck
+
+      # Every `@ts-expect-error` of packages/core/tests/traps.test-d.ts is a
+      # guarantee of the types. A directive goes unused when a refactor widens
+      # the type, and nothing in a green typecheck says so, so each trap is
+      # removed on purpose in a copy of the package and tsc must report
+      # exactly that directive as unused (TS2578).
+      - name: Trap types
+        run: pnpm verify:traps
+
+      # Type-aware rules read @ic-reactor/core's emitted .d.ts through the
+      # workspace symlinks, so this must run after `pnpm build` -- without a
+      # build those types degrade to `any` and no-floating-promises silently
+      # stops reporting. Placed after Type check so a type error surfaces as
+      # tsc's message rather than an ESLint parse error.
+      - name: Lint
+        run: pnpm lint
+
+  typecheck-examples:
+    name: Type Check Examples
+    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-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # Examples import the @ic-reactor/* packages through the workspace symlinks,
+      # so they must be built before type-checking the examples.
+      - name: Build packages
+        run: pnpm build
+
+      - name: Type check examples
+        run: pnpm typecheck:examples
+
+      # Runs each example's own `test` script against the packages built
+      # above. The test job installs without the examples and its `pnpm test`
+      # covers packages/** only, so this is the one job that can run them.
+      # The filter selects examples/* and examples/*/* and nothing else, and
+      # --if-present skips an example that has no tests. The suites run one
+      # after another: each signs and verifies every call on an in-memory
+      # replica, and side by side on a CI runner they starved each other into
+      # timeouts.
+      - name: Test examples
+        run: pnpm -r --workspace-concurrency=1 --filter './examples/**' run --if-present test
+
+      # Compiles the ts/tsx fences of the docs site's hand-written pages. Their
+      # examples import libraries only the example apps install, which is why
+      # this runs here, where the examples are installed and the packages
+      # built, and not in the lint job that installs without them.
+      - name: Docs snippet check
+        run: pnpm check:snippets:docs
+
+      # The docs half of the snippet gate's own tests. It needs the examples'
+      # installs, which the Test job (where the rest of test:scripts runs)
+      # does not have, so scripts/check-snippets.test.mjs skips it there.
+      - name: Test the docs snippet gate
+        run: node --test --test-name-pattern="check:snippets --docs" scripts/check-snippets.test.mjs
+
+      # `tsc` never loads a bundler, so a broken Vite/Next config type-checks
+      # clean. examples/nextjs (Turbopack workspace root) and
+      # examples/nextjs-app-router (Tailwind v4 PostCSS plugin) were both
+      # unbuildable while this job stayed green -- issue #224.
+      - name: Build examples
+        run: pnpm build:examples
+
+  test:
+    name: Test
+    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-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --filter '!./examples/**'
+
+      - name: Build packages
+        run: pnpm build
+
+      - name: Run tests
+        run: pnpm test
+
+      # The gates' own tests: the export budget, the trap verifier, the fault
+      # verifier, check:ai-context, check:stack, check:snippets and the vite
+      # plugin's entry of verify:peer-floors each run against repositories
+      # built for the purpose and must fail where they should. They compile
+      # against the packages built above.
+      - name: Test the gates
+        run: pnpm test:scripts
+
+      # A test that stays green with its bug put back guards nothing. Each
+      # test listed in scripts/faults.json is run against a copy of its
+      # package with the named fault applied and must fail.
+      - name: Fault-proof runtime tests
+        run: pnpm verify:faults
+
+      # Everything above runs against the lockfile, which holds the newest
+      # release of each peer. This pins the peers of core, react and the vite
+      # plugin to the lowest versions their ranges accept and runs typecheck and
+      # tests there, in a throwaway worktree: the vite plugin once for the floor
+      # of each Vite major its range joins (4.2.0, 5.0.0, 6.0.0, 7.0.0, 8.0.0).
+      # react once declared @tanstack/react-query ^5.0.0 while it did not
+      # compile below 5.89 (#475). It also compiles the declarations of core,
+      # react and the vite plugin built above with the oldest supported
+      # TypeScript: the docs said TypeScript 5+ while the declarations needed
+      # 5.7 (#591).
+      - name: Test at the oldest supported peers and TypeScript
+        run: pnpm verify:peer-floors
+
+  # Every other job runs on Linux. The Vite plugin starts child processes
+  # (`icp`, `meant`) and handles paths, where Windows differs: an
+  # npm-installed icp-cli is `icp.cmd` there, which spawn cannot start
+  # (#905). This runs the plugin's whole test suite on Windows. Its first run
+  # here found messages naming `did\ledger.did` where Linux names
+  # `did/ledger.did`, and a temp directory that could not be removed yet
+  # (EBUSY): messages now name relative paths with `/`, and test cleanup tries
+  # the removal again.
+  vite-plugin-windows:
+    name: Vite plugin on Windows
+    runs-on: windows-latest
+    timeout-minutes: 30
+    defaults:
+      run:
+        shell: bash
+    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-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --filter '!./examples/**'
+
+      - name: Build packages
+        run: pnpm build
+
+      - name: Test the Vite plugin
+        run: pnpm --filter @ic-reactor/vite-plugin test
+
+  # The packages declare engines.node >=22.12.0 (#896): the first Node 22 that
+  # loads an ES module with require(), and a floor that can only fall later
+  # without a major release. Every other job runs the newest Node 22, so this
+  # one runs the package tests and a `meant gen` on the floor itself,
+  # after checking that every package's manifest and docs page still name it.
+  # Some dev tools here (jsdom, undici) declare a newer Node than the floor,
+  # and pnpm checks engines against the workspace's nodeVersion, not this
+  # one: a failure inside such a tool on the floor is a dev-tool problem, not
+  # a package regression.
+  node-floor:
+    name: Test on the Node floor
+    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.12.0
+
+      # The corepack bundled with Node 22.12.0 (0.29.4) predates npm's current
+      # signing keys and refuses to fetch pnpm; this exact one does not.
+      - name: Setup pnpm
+        run: |
+          npm install --global corepack@0.34.0
+          corepack enable
+          corepack prepare pnpm@10.30.3 --activate
+          pnpm --version
+
+      - name: The manifests name this Node as their floor
+        run: |
+          node -e '
+            const fs = require("node:fs")
+            const floor = ">=" + process.versions.node
+            for (const p of fs.readdirSync("packages")) {
+              const m = JSON.parse(fs.readFileSync(`packages/${p}/package.json`, "utf8"))
+              if (m.private) continue
+              if (m.engines?.node !== floor) {
+                console.error(`packages/${p}: engines.node is ${m.engines?.node}, expected ${floor}`)
+                process.exitCode = 1
+              }
+              const page = `docs/src/content/docs/packages/${p}.mdx`
+              if (!fs.readFileSync(page, "utf8").includes("Node `" + floor + "`")) {
+                console.error(`${page} does not say Node \`${floor}\``)
+                process.exitCode = 1
+              }
+            }
+          '
+
+      - 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 --filter '!./examples/**'
+
+      - name: Build packages
+        run: pnpm build
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: meant gen
+        working-directory: e2e
+        run: pnpm gen:check
+
+  build:
+    name: Build
+    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-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --filter '!./examples/**'
+
+      - name: Build packages
+        run: pnpm build
+
+      - name: Check package sizes
+        # Core's and react's own code (their peers left out), and what an app
+        # pays with the peers included (scripts/size-app). Every limit is
+        # tight: a change that moves one states its delta and raises it.
+        run: pnpm size
+
+      - name: Verify published artifacts
+        # Packs every publishable package, installs the tarballs into a scratch
+        # project outside the workspace, imports/requires every entry point in real
+        # Node, and runs publint + attw. In-repo consumers reach packages through
+        # workspace symlinks and bundler-mode resolution, so nothing else in CI can
+        # catch a broken published artifact -- which is how 3.7.0 shipped
+        # extensionless ESM specifiers and a cli `types` entry that was never built.
+        run: pnpm verify:packages

package/.github/workflows/codeql.yml

@@ -0,0 +1,41 @@
+name: CodeQL Security Analysis
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Run weekly on Sunday at midnight
+    - cron: "0 0 * * 0"
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [javascript-typescript]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4
+        with:
+          category: "/language:${{ matrix.language }}"

package/.github/workflows/dependency-review.yml

@@ -0,0 +1,68 @@
+name: Dependency Review
+
+# PR-only. dependency-review-action diffs the dependency graph between a base
+# ref and a head ref, so it has nothing to compare against on a push to main --
+# which is also why this cannot live in ci.yml, which runs on both.
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  dependency-review:
+    name: Dependency Review
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Review dependency changes
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5
+        with:
+          fail-on-severity: high
+          # The lockfile entries GitHub reports carry scope "runtime" regardless
+          # of whether the importer is a devDependency, so the default scope
+          # filter would not hide them. Manifest entries for devDependencies do
+          # come through as "development" and would be filtered, so both scopes
+          # are named explicitly rather than relying on that asymmetry.
+          fail-on-scopes: runtime, development
+
+  audit:
+    name: Audit
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    # Deliberately install-free: `pnpm audit` resolves the whole workspace from
+    # pnpm-lock.yaml and never reads node_modules, so this job needs no pnpm
+    # store cache and no Rust toolchain, unlike every other job in this repo.
+    #
+    # dependency-review-action alone would not have caught what motivated this
+    # gate. It diffs base against head, so it only reports dependencies a PR
+    # introduces or upgrades into a vulnerable version -- it is blind to a
+    # dependency that was already on main and became vulnerable later, when a new
+    # advisory was published against a version the lockfile had pinned all along.
+    # That is exactly how four high-severity fast-uri advisories went unnoticed.
+    # This job re-audits the whole tree on every PR, so decay surfaces.
+    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: Audit the workspace
+        run: pnpm verify:audit

package/.github/workflows/docs-check.yml

@@ -0,0 +1,98 @@
+name: Docs validation (PR)
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "packages/**"
+      - "packages/**/src/content/**"
+      # check-example-docs.mjs validates the docs against the examples/ tree, so
+      # renaming an example file can break a page without touching docs/.
+      - "examples/**"
+
+permissions:
+  contents: read
+
+jobs:
+  # The pages link Candid Core's site, which the deploy serves at
+  # /candid-core/ from that repository's main, built in a job of its own
+  # (docs.yml, `candid-core-site`); the link check mounts the same build here.
+  candid-core-site:
+    name: Build Candid Core's site
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          repository: B3Pay/Meant
+          ref: main
+          persist-credentials: false
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: "24.18.0"
+      - name: Build
+        run: |
+          set -euo pipefail
+          node website/build.mjs
+          echo "Candid Core's site is built from B3Pay/Meant@$(git rev-parse HEAD)." >> "$GITHUB_STEP_SUMMARY"
+      - 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
+
+  # Runs when Candid Core's site does not build, too, so the lint and the
+  # build still report; the link check then fails, for want of the site.
+  validate-docs:
+    name: MDX lint + docs build
+    needs: candid-core-site
+    if: ${{ !cancelled() }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - 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-
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: MDX lint
+        working-directory: ./docs
+        run: pnpm run lint:mdx
+      # Needs no build. Running it first fails a broken example link in seconds
+      # rather than after the full docs build.
+      - name: Check example docs
+        run: pnpm docs:check-examples
+      - name: Build docs
+        run: pnpm docs:build
+
+      - name: Download Candid Core's site
+        if: needs.candid-core-site.result == 'success'
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: candid-core-site
+          path: candid-core-site
+
+      - name: Check links
+        env:
+          CANDID_CORE_SITE: ${{ github.workspace }}/candid-core-site
+        run: pnpm docs:check-links