@mokoenterprises/mokoabs-mcp 0.0.0-stage → 4.2.1

package/.mokogit/workflows/npm-build-test.yml

@@ -0,0 +1,544 @@
+# MCP Server Build & Validation
+# Copyright (C) 2026 Moko Enterprises <hello@mokoenterprises.us>
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# Builds the MCP server via the centralized MokoCLI build agent
+# (moko lint|build|test), then validates that compiled output exists and that
+# tools are properly registered. The build agent is platform-aware via the
+# repo's NATIVE manifest (package.json) — no metadata API call — so inline
+# Deps are installed via `npm ci` below so `moko lint|build|test` (which run
+# `npx --no-install tsc`/eslint) can find typescript/eslint from devDependencies.
+#
+# moko: the build job bootstraps mokocli at runtime — it prefers a pre-installed
+# /opt/mokocli, else installs fresh from the public MokoGIT Composer registry (the
+# same tokenless path the release workflows use) and puts `moko` first on PATH, so
+# `moko lint|build|test` resolve without waiting on a runner-image rebuild.
+
+name: "MCP: Build & Validate"
+
+on:
+  push:
+    branches: [main, stable, dev, dev/**]
+    paths: ['source/**', 'src/**', 'package.json', 'tsconfig.json']
+  pull_request:
+    branches: [main, stable, rc, dev]
+    # No paths filter: the folded-in universal pr-check jobs (Branch Policy,
+    # Require Docs, Wiki Reminder) must run on EVERY PR.
+
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write            # folded-in Wiki Reminder posts a sticky PR comment
+
+env:
+  MOKOGIT_URL: ${{ vars.MOKOGIT_URL || 'https://git.mokoenterprises.us' }}
+  GIT_ORG: ${{ vars.MOKOGIT_ORG || github.repository_owner }}
+  GIT_REPO: ${{ vars.MOKOGIT_REPO || github.event.repository.name }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: ${{ !startsWith(github.event.repository.name, 'Template-') }}
+    strategy:
+      matrix:
+        node-version: [20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Reject base64-encoded source files
+        run: |
+          set -uo pipefail
+          # A tracked source file that is a single line of pure base64 (no code
+          # punctuation) is almost always a double-encoding accident: it breaks the
+          # TypeScript/PHP build at EOF and reads as an opaque blob. Fail fast so it
+          # is caught at commit time and never hand-decoded later. The strict
+          # ^[A-Za-z0-9+/]{200,}={0,2}$ full-line match cannot hit minified JS or
+          # JSON (both carry punctuation within the first 200 chars); an embedded
+          # base64 literal assigned in code is also safe (it is preceded by
+          # `=`/`"`/`export`, so the file does not START with base64).
+          bad=0
+          while IFS= read -r f; do
+            case "$f" in
+              *.ts|*.tsx|*.js|*.mjs|*.cjs|*.jsx|*.php) ;;
+              *) continue ;;
+            esac
+            case "$f" in *.min.js|*/dist/*|*/vendor/*|*/node_modules/*) continue ;; esac
+            [ -s "$f" ] || continue
+            if [ "$(wc -l < "$f")" -le 1 ] \
+               && head -c 400 "$f" | LC_ALL=C grep -qE '^[A-Za-z0-9+/]{200,}={0,2}$'; then
+              echo "::error file=${f}::Source file looks base64-encoded (single base64-only line) — decode it before committing (e.g. base64 -d)."
+              bad=$((bad + 1))
+            fi
+          done < <(git ls-files)
+          if [ "$bad" -gt 0 ]; then
+            echo "${bad} base64-encoded source file(s) found — see annotations above." >&2
+            exit 1
+          fi
+          echo "No base64-encoded source files."
+
+      - name: Resolve source dir
+        id: srcdir
+        uses: ./.mokogit/actions/resolve-source-dir
+        with:
+          mokogit_token: ${{ secrets.MOKOGIT_TOKEN }}
+          strict: 'false'
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install npm dependencies
+        run: |
+          if [ -f package-lock.json ]; then npm ci; else npm install --no-audit --no-fund; fi
+
+      - name: Setup MokoCLI build agent (moko on PATH)
+        env:
+          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGIT_TOKEN }}
+          MOKO_CLONE_HOST: git.mokoenterprises.us/MokoEnterprises
+        run: |
+          # Reach mokocli deterministically and expose `moko` on PATH (mokocli's cli/ dir)
+          # so `moko build|test|lint` resolve. Prefer a pre-installed /opt/mokocli ONLY
+          # when it is a live git checkout we can fast-forward (i.e. genuinely current).
+          # A `cp -a` snapshot (host mokocli-sync) or a checkout that will not ff is NOT
+          # trusted — we fall through to the CURRENT public Composer registry instead.
+          # This removes the dependency on the host mokocli-sync service being healthy:
+          # a stale /opt snapshot previously ran frozen mokocli (observed v04.00.15)
+          # because the git-pull refresh is a silent no-op against a non-git snapshot,
+          # which reds every npm repo (the local-bin lint skip / repo lint-script path).
+          # (MokoCLI #650 rotting-/opt failsafe; #1028/#1029 the lint fix that exposed
+          # the staleness; non-executable-/opt exit-126 heal retained — Template-NPM
+          # #142 / #138.)
+
+          # Install the CURRENT published mokocli from the tokenless public Composer
+          # registry (metadata + dist need no auth); authenticated git clone of stable
+          # is the last-resort fallback. Exposes `moko` on PATH via /tmp/mokocli/cli.
+          bootstrap_registry() {
+            if ! command -v composer > /dev/null 2>&1; then
+              sudo apt-get update -qq && sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl composer > /dev/null 2>&1
+            fi
+            rm -rf /tmp/mokocli
+            REG='{"type":"composer","url":"https://git.mokoenterprises.us/api/packages/MokoEnterprises/composer"}'
+            if composer create-project --no-dev --no-interaction --no-progress --quiet --repository="${REG}" mokoenterprises/mokocli /tmp/mokocli >/dev/null 2>&1 && { [ -x /tmp/mokocli/cli/moko ] || [ -f /tmp/mokocli/cli/moko ]; }; then
+              echo "Bootstrapped mokocli from the Composer registry (tokenless)."
+            else
+              echo "Registry bootstrap unavailable; falling back to authenticated git clone."
+              MOKO_CLONE_TOKEN="$(printf '%s' "${MOKO_CLONE_TOKEN}" | tr -d '[:space:]')"
+              echo "::add-mask::${MOKO_CLONE_TOKEN}"
+              if [ -z "${MOKO_CLONE_TOKEN}" ]; then
+                echo "::error::mokocli registry bootstrap failed and MOKOGIT_TOKEN is empty — cannot clone fallback." >&2
+                return 1
+              fi
+              rm -rf /tmp/mokocli
+              git clone --depth 1 --branch stable --quiet "https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/mokocli.git" /tmp/mokocli
+              ( cd /tmp/mokocli && composer install --no-dev --no-interaction --no-progress --optimize-autoloader --quiet )
+            fi
+            # Ensure the freshly-bootstrapped binary is executable (registry dist / git
+            # clone can land it without +x on some runners).
+            chmod +x /tmp/mokocli/*/moko 2>/dev/null || true
+            echo "/tmp/mokocli/cli" >> "$GITHUB_PATH"
+          }
+
+          # Heal a non-executable pre-installed binary before testing it (exit-126 class).
+          sudo chmod +x /opt/mokocli/*/moko 2>/dev/null || true
+
+          OPT_OK=0
+          if [ -x /opt/mokocli/cli/moko ] && git -C /opt/mokocli rev-parse --git-dir > /dev/null 2>&1; then
+            # Live git checkout: trust it ONLY if it fast-forwards cleanly to current.
+            if git -C /opt/mokocli pull --ff-only --quiet 2>/dev/null; then
+              echo "Using pre-installed /opt/mokocli (git-refreshed to current)."
+              echo "/opt/mokocli/cli" >> "$GITHUB_PATH"
+              OPT_OK=1
+            else
+              echo "/opt/mokocli could not fast-forward — using the current registry instead."
+            fi
+          elif [ -x /opt/mokocli/cli/moko ]; then
+            echo "/opt/mokocli is a non-git snapshot (freshness unverifiable) — using the current registry instead."
+          fi
+
+          if [ "$OPT_OK" != "1" ]; then
+            bootstrap_registry || exit 1
+          fi
+
+      - name: Lint
+        run: moko lint
+
+      - name: Build
+        run: moko build
+
+      - name: Test
+        run: |
+          # Skip cleanly when the package defines no "test" script, so a repo
+          # with genuinely no tests does not red-fail the build. moko test runs
+          # the script when it exists.
+          if node -e "process.exit(((require('./package.json').scripts)||{}).test?0:1)" 2>/dev/null; then
+            moko test
+          else
+            echo "::notice::no \"test\" script in package.json -- skipping test step"
+          fi
+
+      - name: Verify dist output exists
+        run: |
+          # dist/index.js is the bin/main entry for every MCP server (shared
+          # package.json convention). Assert that + that the build emitted
+          # compiled output. Do NOT hard-code other filenames: source layouts
+          # differ per server (many have no client.ts/types.ts/root config.ts),
+          # which false-failed this check on every build fleet-wide.
+          test -f dist/index.js || (echo "ERROR: dist/index.js not found" && exit 1)
+          JS_COUNT=$(find dist -name '*.js' | wc -l)
+          [ "${JS_COUNT}" -gt 0 ] || (echo "ERROR: no compiled .js files in dist/" && exit 1)
+          echo "✓ dist/index.js present; ${JS_COUNT} compiled .js file(s) in dist/"
+
+      - name: Verify shebang in index.js
+        run: |
+          head -1 dist/index.js | grep -q "#!/usr/bin/env node" || echo "WARNING: Missing shebang in dist/index.js"
+
+      - name: Count registered tools
+        run: |
+          # Tools may be registered in the entry file OR in modules it imports
+          # (modular servers call server.tool( / .registerTool( inside
+          # source/tools/*.ts). Count registrations across the whole source
+          # tree, not just index.ts, else modular servers false-report zero.
+          SRC_DIR="${{ steps.srcdir.outputs.source_dir }}"
+          [ -n "${SRC_DIR}" ] && [ -d "${SRC_DIR}" ] || SRC_DIR="source"
+          [ -d "${SRC_DIR}" ] || SRC_DIR="src"
+          # `grep` exits 1 when it finds no matches; under `set -e -o pipefail`
+          # that aborts the step before the MCP-vs-non-MCP check below can run.
+          # Swallow the no-match exit so the count is a real 0, not a hard fail.
+          TOOL_COUNT=$( { grep -rE "server\.tool\(|\.registerTool\(" "${SRC_DIR}" 2>/dev/null || true; } | wc -l | tr -d ' ')
+          # Only MCP *servers* must register tools. Detect that from package.json
+          # (any @modelcontextprotocol/* dep) so non-MCP npm packages — client
+          # CLIs, libraries — aren't force-failed by an inapplicable check. When
+          # this npm CI template lands on a non-MCP repo the tool count is 0 by
+          # design; treat that as advisory, not a hard error.
+          IS_MCP=$(node -e "try{var p=require('./package.json');var d=Object.assign({},p.dependencies,p.devDependencies,p.peerDependencies);process.stdout.write(Object.keys(d).some(function(k){return k.indexOf('@modelcontextprotocol/')===0;})?'1':'0');}catch(e){process.stdout.write('0');}")
+          echo "Registered tool calls under ${SRC_DIR}: ${TOOL_COUNT} (mcp-server=${IS_MCP})"
+          if [ "${TOOL_COUNT}" -eq 0 ]; then
+            if [ "${IS_MCP}" = "1" ]; then
+              echo "ERROR: MCP server declares @modelcontextprotocol/* but registers no tools under ${SRC_DIR}"
+              exit 1
+            fi
+            echo "::warning::No MCP tool registrations found and no @modelcontextprotocol/* dependency — treating as a non-MCP npm package (advisory, not failing)."
+          fi
+
+  # NOTE: a standalone `ci-summary` job (needs: [build], if: always()) was removed.
+  # This Gitea act_runner never schedules a `needs:`+`if: always()` job — it parks in
+  # "waiting" (runner_id 0) forever and never dispatches. Under the org-governance
+  # `main` rule (status_check_contexts: ["*"], every check must be green) that stranded
+  # job was a permanent, silent block on every PR into main. The per-job status is
+  # already visible on the Actions run page and `wiki-reminder` posts a sticky PR
+  # comment on main PRs, so a separate summary job earned its keep only when it worked —
+  # which, on this runner, was never. If a build-result summary comment is wanted back,
+  # add it as a final STEP with `if: ${{ always() }}` inside the `build` job (step-level
+  # always() IS supported), not as a dependent job. (Matches ci-go.yml.)
+
+  # ══════════════════════════════════════════════════════════════════════════
+  #  Universal PR-check jobs — folded in from "Universal: PR Check" so the NPM
+  #  platform runs one CI workflow per PR (mirrors Template-Joomla #162).
+  #  Branch-gated: Branch Policy on all PRs; docs gate + wiki reminder on main.
+  # ══════════════════════════════════════════════════════════════════════════
+
+  branch-policy:
+    name: Branch Policy
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check branch merge target
+        env:
+          # Compare against the repo's real production branch, not a hardcoded
+          # 'main'. MokoGIT renamed the production channel main -> stable
+          # fleet-wide (ladder: dev -> rc -> stable); hardcoding 'main'
+          # red-failed every legitimate dev->stable / rc->stable promotion.
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          HEAD="${{ github.head_ref }}"
+          BASE="${{ github.base_ref }}"
+          PROD="${DEFAULT_BRANCH:-main}"
+
+          echo "PR: ${HEAD} → ${BASE} (production=${PROD})"
+
+          ALLOWED=true
+          REASON=""
+
+          case "$HEAD" in
+            feature/*|feat/*)
+              if [ "$BASE" != "dev" ]; then
+                ALLOWED=false
+                REASON="Feature branches must target 'dev', not '${BASE}'"
+              fi
+              ;;
+            fix/*|bugfix/*)
+              if [ "$BASE" != "dev" ] && [ "$BASE" != "$PROD" ]; then
+                ALLOWED=false
+                REASON="Fix branches must target 'dev' or '${PROD}', not '${BASE}'"
+              fi
+              ;;
+            patch/*)
+              if [ "$BASE" != "dev" ] && [ "$BASE" != "rc" ] && [ "$BASE" != "$PROD" ]; then
+                ALLOWED=false
+                REASON="Patch branches must target 'dev', 'rc', or '${PROD}', not '${BASE}'"
+              fi
+              ;;
+            hotfix/*)
+              if [ "$BASE" != "dev" ] && [ "$BASE" != "$PROD" ]; then
+                ALLOWED=false
+                REASON="Hotfix branches can only target 'dev' or '${PROD}', not '${BASE}'"
+              fi
+              ;;
+            rc|rc/*)
+              if [ "$BASE" != "$PROD" ]; then
+                ALLOWED=false
+                REASON="RC branch can only merge into '${PROD}', not '${BASE}'"
+              fi
+              ;;
+            dev)
+              if [ "$BASE" != "rc" ] && [ "$BASE" != "$PROD" ]; then
+                ALLOWED=false
+                REASON="Dev branch can only merge into 'rc' or '${PROD}', not '${BASE}'"
+              fi
+              ;;
+          esac
+
+          if [ "$ALLOWED" = false ]; then
+            echo "::error::${REASON}"
+            echo "## Branch Policy Violation" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "${REASON}" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### Allowed merge paths:" >> $GITHUB_STEP_SUMMARY
+            echo "- \`feature/*\` → \`dev\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`fix/*\` → \`dev\` or \`${PROD}\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`patch/*\` → \`dev\`, \`rc\`, or \`${PROD}\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`hotfix/*\` → \`dev\` or \`${PROD}\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`dev\` → \`rc\` or \`${PROD}\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`rc/*\` → \`${PROD}\`" >> $GITHUB_STEP_SUMMARY
+            exit 1
+          fi
+
+          echo "Branch policy: OK (${HEAD} → ${BASE})"
+          echo "## Branch Policy: Passed" >> $GITHUB_STEP_SUMMARY
+
+  # ── Docs Update Gate (wiki-aware) ───────────────────────────────────────
+  #
+  # RULE (in order):
+  #   1. Short-circuit: if the PR diff touches CHANGELOG.md OR README.md, PASS
+  #      immediately (deterministic; no wiki lookup).
+  #   2. Else consult the repo WIKI (<owner>/<repo>.wiki.git) HEAD commit date.
+  #      Mode is chosen by the org/repo variable DOCS_WIKI_WINDOW (default 'pr'):
+  #        - 'pr'          → satisfied if wiki HEAD commit date >= this PR's
+  #                          created_at (docs touched since the PR opened).
+  #        - '<N>h'/'<N>d' → satisfied if wiki HEAD commit is within that rolling
+  #                          window (now - duration). e.g. 24h, 72h, 7d.
+  #      Fail-open: if the wiki is absent/unreachable or the lookup errors, do
+  #      NOT hard-fail — treat as "unsatisfied → warn" per step 3.
+  #   3. Verdict: if neither is satisfied → emit ::warning:: (advisory) and PASS
+  #      on non-main branches; hard-fail (exit 1) ONLY when the PR base is 'main'
+  #      (release hygiene on the stable line).
+  #
+  # The job runs on EVERY PR so the required status context "Require Docs Update"
+  # always reports; the base-branch gate is enforced inside the step, not via a
+  # job-level `if:` that would leave the context missing on non-main PRs.
+  require-docs:
+    name: Require Docs Update
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Docs gate (docs diff, else wiki freshness)
+        env:
+          BASE_REF: ${{ github.base_ref }}
+          HEAD_REF: ${{ github.head_ref }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          PR_CREATED_AT: ${{ github.event.pull_request.created_at }}
+          SERVER: ${{ vars.MOKOGIT_URL || 'https://git.mokoenterprises.us' }}
+          REPO: ${{ github.repository }}
+          TOKEN: ${{ github.token }}
+          DOCS_WIKI_WINDOW: ${{ vars.DOCS_WIKI_WINDOW || 'pr' }}
+        run: |
+          set -uo pipefail
+
+          # ── Step 1: docs diff short-circuit ─────────────────────────────
+          CHANGED="$(git diff --name-only "$BASE_SHA" "$HEAD_SHA" 2>/dev/null || true)"
+          if [ -z "$CHANGED" ]; then
+            git fetch -q origin "$BASE_REF" 2>/dev/null || true
+            CHANGED="$(git diff --name-only "origin/${BASE_REF}...HEAD" 2>/dev/null || true)"
+          fi
+          echo "Changed files in PR:"
+          echo "$CHANGED"
+          if echo "$CHANGED" | grep -qxE 'CHANGELOG\.md|README\.md'; then
+            echo "Docs diff present (CHANGELOG.md or README.md) — gate satisfied."
+            echo "## Docs Update: Passed (docs diff)" >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+
+          # ── Step 2: wiki freshness (fail-open) ──────────────────────────
+          # Resolve wiki HEAD commit epoch via a shallow clone of the wiki repo.
+          # Any failure here is non-fatal: SATISFIED stays 0 → handled by step 3.
+          SATISFIED=0
+          WIKI_EPOCH=""
+          TOK="$(printf '%s' "${TOKEN:-}" | tr -d '[:space:]')"
+          HOSTPATH="${SERVER#https://}"; HOSTPATH="${HOSTPATH#http://}"
+          WIKI_URL="https://x-access-token:${TOK}@${HOSTPATH}/${REPO}.wiki.git"
+          echo "::add-mask::${TOK}"
+          rm -rf /tmp/docs-wiki
+          if git clone --depth 1 --quiet "${WIKI_URL}" /tmp/docs-wiki 2>/dev/null; then
+            WIKI_EPOCH="$(git -C /tmp/docs-wiki log -1 --format=%ct 2>/dev/null || true)"
+          fi
+
+          if [ -z "$WIKI_EPOCH" ]; then
+            echo "::warning::wiki absent/unreachable — treating docs gate as unsatisfied (fail-open)"
+          else
+            MODE="$(printf '%s' "${DOCS_WIKI_WINDOW}" | tr '[:upper:]' '[:lower:]' | tr -d '[:space:]')"
+            [ -n "$MODE" ] || MODE="pr"
+            if [ "$MODE" = "pr" ]; then
+              # PASS if wiki HEAD commit date >= PR created_at.
+              PR_EPOCH="$(date -u -d "${PR_CREATED_AT}" +%s 2>/dev/null || true)"
+              if [ -z "$PR_EPOCH" ]; then
+                echo "::warning::could not parse PR created_at ('${PR_CREATED_AT}') — docs gate unsatisfied (fail-open)"
+              elif [ "$WIKI_EPOCH" -ge "$PR_EPOCH" ]; then
+                SATISFIED=1
+                echo "Wiki updated since PR opened (wiki=${WIKI_EPOCH} >= pr=${PR_EPOCH})."
+              else
+                echo "Wiki not updated since PR opened (wiki=${WIKI_EPOCH} < pr=${PR_EPOCH})."
+              fi
+            else
+              # Duration window: <N>h / <N>d (also bare <N> = seconds).
+              NUM="$(printf '%s' "$MODE" | sed -E 's/[^0-9].*$//')"
+              UNIT="$(printf '%s' "$MODE" | sed -E 's/^[0-9]+//')"
+              SECS=0
+              case "$UNIT" in
+                h)   SECS=$(( NUM * 3600 )) ;;
+                d)   SECS=$(( NUM * 86400 )) ;;
+                m)   SECS=$(( NUM * 60 )) ;;
+                s|"") SECS=$(( NUM )) ;;
+                *)   echo "::warning::unrecognized DOCS_WIKI_WINDOW unit '${UNIT}'; falling back to 'pr'-style (>= PR created_at)"
+                     PR_EPOCH="$(date -u -d "${PR_CREATED_AT}" +%s 2>/dev/null || echo 0)"
+                     SECS=0 ;;
+              esac
+              if [ "$SECS" -gt 0 ]; then
+                NOW="$(date -u +%s)"
+                CUTOFF=$(( NOW - SECS ))
+                if [ "$WIKI_EPOCH" -ge "$CUTOFF" ]; then
+                  SATISFIED=1
+                  echo "Wiki updated within window ${MODE} (wiki=${WIKI_EPOCH} >= cutoff=${CUTOFF})."
+                else
+                  echo "Wiki stale beyond window ${MODE} (wiki=${WIKI_EPOCH} < cutoff=${CUTOFF})."
+                fi
+              elif [ "${PR_EPOCH:-0}" -gt 0 ] && [ "$WIKI_EPOCH" -ge "${PR_EPOCH}" ]; then
+                SATISFIED=1
+              fi
+            fi
+          fi
+
+          # ── Step 3: verdict ─────────────────────────────────────────────
+          if [ "$SATISFIED" = "1" ]; then
+            echo "## Docs Update: Passed (wiki fresh)" >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+
+          if [ "$BASE_REF" = "main" ]; then
+            echo "::error::Docs gate unsatisfied: no CHANGELOG.md/README.md change and wiki not fresh (DOCS_WIKI_WINDOW='${DOCS_WIKI_WINDOW}'). Required on PRs into main."
+            {
+              echo "## Docs Update Required"
+              echo ""
+              echo "PRs merging into \`main\` must either update **CHANGELOG.md** or **README.md**, or the repo **wiki** must be fresh (mode: \`${DOCS_WIKI_WINDOW}\`)."
+            } >> "$GITHUB_STEP_SUMMARY"
+            exit 1
+          fi
+
+          echo "::warning::Docs gate unsatisfied (advisory on non-main branch '${BASE_REF}'): update CHANGELOG.md/README.md or the wiki."
+          {
+            echo "## Docs Update: Advisory"
+            echo ""
+            echo "No docs diff and wiki not fresh (mode: \`${DOCS_WIKI_WINDOW}\`). Non-blocking on \`${BASE_REF}\`; will hard-fail on \`main\`."
+          } >> "$GITHUB_STEP_SUMMARY"
+          exit 0
+
+  wiki-reminder:
+    name: Wiki Update Reminder
+    runs-on: ubuntu-latest
+    if: ${{ github.base_ref == github.event.repository.default_branch }}
+    steps:
+      - name: Remind to update the wiki
+        env:
+          TOKEN: ${{ github.token }}
+          SERVER: ${{ vars.MOKOGIT_URL || 'https://git.mokoenterprises.us' }}
+          REPO: ${{ github.repository }}
+          PR: ${{ github.event.pull_request.number }}
+        run: |
+          set -uo pipefail
+          {
+            echo "## Wiki Update Reminder"
+            echo ""
+            echo "Docs are **wiki-first** at MokoEnterprises. If this change affects behavior, usage, configuration, or standards, update the repo wiki:"
+            echo ""
+            echo "- ${SERVER}/${REPO}/wiki"
+            echo ""
+            echo "_Non-blocking reminder._"
+          } >> "$GITHUB_STEP_SUMMARY"
+          # Sticky PR comment: create-or-UPDATE a single comment keyed by a hidden
+          # marker (no duplicate reminders across pushes). Best-effort, never fails.
+          LIST="${SERVER}/api/v1/repos/${REPO}/issues/${PR}/comments"
+          EDIT="${SERVER}/api/v1/repos/${REPO}/issues/comments"
+          MARKER="<!-- wiki-reminder -->"
+          BODY="$(printf '%s\n\n%s' "${MARKER}" "**Wiki reminder:** docs are wiki-first -- if this PR changes behavior, usage, config, or standards, please update the repo wiki before/after merge. _(non-blocking)_")"
+          if [ -n "${TOKEN:-}" ] && [ -n "${PR:-}" ]; then
+            CID="$(curl -sf -H "Authorization: token ${TOKEN}" "${LIST}?limit=100" 2>/dev/null \
+                   | python3 -c "import sys,json; c=[x for x in json.load(sys.stdin) if '${MARKER}' in (x.get('body') or '')]; print(c[-1]['id'] if c else '')" 2>/dev/null || true)"
+            PAYLOAD="$(python3 -c "import json,sys; print(json.dumps({'body': sys.stdin.read()}))" <<<"${BODY}")"
+            if [ -n "${CID}" ]; then
+              curl -sf -X PATCH -H "Authorization: token ${TOKEN}" -H "Content-Type: application/json" -d "${PAYLOAD}" "${EDIT}/${CID}" >/dev/null 2>&1 || true
+            else
+              curl -sf -X POST  -H "Authorization: token ${TOKEN}" -H "Content-Type: application/json" -d "${PAYLOAD}" "${LIST}" >/dev/null 2>&1 || true
+            fi
+          fi
+          echo "Wiki reminder emitted (non-blocking, sticky)."
+
+  # ── Universal PR gate checks (folded from pr-check's Validate PR) ─────────
+  pr-gate-checks:
+    name: PR Gate Checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Check for merge conflict markers
+        run: |
+          CONFLICTS=$(grep -rn '<<<<<<< \|>>>>>>> \|^=======$' --exclude-dir='.git' --exclude-dir='.mokogit' --include='*.php' --include='*.xml' --include='*.css' --include='*.js' --include='*.json' --include='*.md' --include='*.yml' --include='*.yaml' --include='*.ini' --include='*.txt' . 2>/dev/null | grep -v '.git/' || true)
+          if [ -n "$CONFLICTS" ]; then
+            echo "::error::Merge conflict markers found in source files"
+            echo "## Conflict Markers Found" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            echo "$CONFLICTS" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            exit 1
+          fi
+          echo "No conflict markers found"
+
+      - name: Reject .gitea and .github workflow dirs
+        run: |
+          # .gitea/ and .github/ carry their own workflows that CONFLICT with the
+          # MokoGIT .mokogit/workflows/ system (duplicate / competing runs). They
+          # must never exist in-repo. Fail the PR if either directory is tracked so
+          # it gets deleted.
+          HITS=$(git ls-files | grep -E '^(\.gitea|\.github)/workflows/' || true)
+          if [ -n "$HITS" ]; then
+            echo "::error::.gitea/ and .github/ are not allowed - their workflows conflict with .mokogit/workflows/. Delete these directories."
+            printf '%s\n' "$HITS" | while IFS= read -r f; do
+              [ -n "$f" ] && echo "::error file=${f}::Remove ${f} (.gitea/.github workflows conflict with .mokogit/)"
+            done
+            {
+              echo "## Blocked: .gitea/.github present"
+              echo "These directories conflict with the MokoGIT \`.mokogit/workflows/\` system and must be deleted:"
+              echo '```'
+              printf '%s\n' "$HITS"
+              echo '```'
+            } >> "$GITHUB_STEP_SUMMARY"
+            exit 1
+          fi
+          echo "No .gitea/.github dirs - OK"

package/.mokogit/workflows/npm-sdk-check.yml

@@ -0,0 +1,110 @@
+# MCP SDK Version Check
+# Copyright (C) 2026 Moko Enterprises <hello@mokoenterprises.us>
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# Weekly check for MCP SDK updates. Creates an issue when a new version
+# of @modelcontextprotocol/sdk is available.
+
+name: "MCP: SDK Version Check"
+
+on:
+  schedule:
+    - cron: '0 9 * * 1'  # Every Monday at 9am UTC
+  workflow_dispatch:
+
+
+permissions:
+  contents: read
+
+jobs:
+  check-sdk:
+    runs-on: ubuntu-latest
+    if: ${{ !startsWith(github.event.repository.name, 'Template-') }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Check for SDK updates
+        id: sdk-check
+        run: |
+          CURRENT=$(node -p "require('./package.json').dependencies['@modelcontextprotocol/sdk']" | sed 's/[\^~]//')
+          LATEST=$(npm view @modelcontextprotocol/sdk version 2>/dev/null || echo "unknown")
+
+          echo "current=${CURRENT}" >> $GITHUB_OUTPUT
+          echo "latest=${LATEST}" >> $GITHUB_OUTPUT
+
+          if [ "${CURRENT}" != "${LATEST}" ] && [ "${LATEST}" != "unknown" ]; then
+            echo "update_available=true" >> $GITHUB_OUTPUT
+            echo "MCP SDK update available: ${CURRENT} → ${LATEST}"
+          else
+            echo "update_available=false" >> $GITHUB_OUTPUT
+            echo "MCP SDK is up to date: ${CURRENT}"
+          fi
+
+      - name: Check for Zod updates
+        id: zod-check
+        run: |
+          CURRENT=$(node -p "require('./package.json').dependencies['zod']" | sed 's/[\^~]//')
+          LATEST=$(npm view zod version 2>/dev/null || echo "unknown")
+
+          echo "current=${CURRENT}" >> $GITHUB_OUTPUT
+          echo "latest=${LATEST}" >> $GITHUB_OUTPUT
+
+          if [ "${CURRENT}" != "${LATEST}" ] && [ "${LATEST}" != "unknown" ]; then
+            echo "update_available=true" >> $GITHUB_OUTPUT
+          else
+            echo "update_available=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create update issue
+        if: steps.sdk-check.outputs.update_available == 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const title = `chore(deps): update @modelcontextprotocol/sdk ${process.env.CURRENT} → ${process.env.LATEST}`;
+            const body = [
+              '## MCP SDK Update Available',
+              '',
+              `| Package | Current | Latest |`,
+              `|---------|---------|--------|`,
+              `| @modelcontextprotocol/sdk | ${process.env.CURRENT} | ${process.env.LATEST} |`,
+              `| zod | ${process.env.ZOD_CURRENT} | ${process.env.ZOD_LATEST} |`,
+              '',
+              '### Steps',
+              '1. Update package.json',
+              '2. Run `npm install`',
+              '3. Run `npm run build` to verify compilation',
+              '4. Test all tools against target API',
+              '',
+              '### Changelog',
+              `https://github.com/modelcontextprotocol/typescript-sdk/releases`,
+            ].join('\n');
+
+            // Check for existing open issue
+            const existing = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              labels: 'api-change',
+            });
+
+            const alreadyExists = existing.data.some(i => i.title.includes('@modelcontextprotocol/sdk'));
+            if (!alreadyExists) {
+              await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title,
+                body,
+                labels: ['api-change', 'chore'],
+              });
+            }
+        env:
+          CURRENT: ${{ steps.sdk-check.outputs.current }}
+          LATEST: ${{ steps.sdk-check.outputs.latest }}
+          ZOD_CURRENT: ${{ steps.zod-check.outputs.current }}
+          ZOD_LATEST: ${{ steps.zod-check.outputs.latest }}