@mokoconsulting/mcp-mokosuite 1.1.0-dev.372 → 1.1.0

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

@@ -6,7 +6,8 @@
 # (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
-# npm install / npx tsc / npm run build / npm test are no longer needed here.
+# 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.
 #
 # GATE: `moko` is provided by mokocli on the runner PATH (/opt/mokocli/cli).
 # It becomes available only after the mokocli build agent lands on `main` and
@@ -21,12 +22,14 @@ on:
     paths: ['source/**', 'src/**', 'package.json', 'tsconfig.json']
   pull_request:
     branches: [main]
-    paths: ['source/**', 'src/**', 'package.json', 'tsconfig.json']
+    # 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.mokoconsulting.tech' }}
@@ -56,6 +59,10 @@ jobs:
         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 }}
@@ -128,40 +135,315 @@ jobs:
             exit 1
           fi
 
-  ci-summary:
-    name: CI Summary (sticky comment)
+  # 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
+        run: |
+          HEAD="${{ github.head_ref }}"
+          BASE="${{ github.base_ref }}"
+
+          echo "PR: ${HEAD} → ${BASE}"
+
+          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" != "main" ]; then
+                ALLOWED=false
+                REASON="Fix branches must target 'dev' or 'main', not '${BASE}'"
+              fi
+              ;;
+            patch/*)
+              if [ "$BASE" != "dev" ] && [ "$BASE" != "rc" ] && [ "$BASE" != "main" ]; then
+                ALLOWED=false
+                REASON="Patch branches must target 'dev', 'rc', or 'main', not '${BASE}'"
+              fi
+              ;;
+            hotfix/*)
+              if [ "$BASE" != "dev" ] && [ "$BASE" != "main" ]; then
+                ALLOWED=false
+                REASON="Hotfix branches can only target 'dev' or 'main', not '${BASE}'"
+              fi
+              ;;
+            rc)
+              if [ "$BASE" != "main" ]; then
+                ALLOWED=false
+                REASON="RC branch can only merge into 'main', not '${BASE}'"
+              fi
+              ;;
+            dev)
+              if [ "$BASE" != "main" ]; then
+                ALLOWED=false
+                REASON="Dev branch can only merge into 'main', 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 \`main\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`patch/*\` → \`dev\`, \`rc\`, or \`main\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`hotfix/*\` → \`dev\` or \`main\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`dev\` → \`main\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`rc/*\` → \`main\`" >> $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.mokoconsulting.tech' }}
+          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
-    needs: [build]
-    if: always()
+    if: ${{ github.base_ref == 'main' }}
     steps:
-      - name: Upsert sticky CI summary comment
+      - name: Remind to update the wiki
         env:
-          TOKEN: ${{ secrets.MOKOGIT_TOKEN || github.token }}
+          TOKEN: ${{ github.token }}
           SERVER: ${{ vars.MOKOGIT_URL || 'https://git.mokoconsulting.tech' }}
           REPO: ${{ github.repository }}
           PR: ${{ github.event.pull_request.number }}
-          BUILD: ${{ needs.build.result }}
-          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
-          HEAD_REF: ${{ github.head_ref }}
-          BASE_REF: ${{ github.base_ref }}
         run: |
           set -uo pipefail
-          { [ -n "${TOKEN:-}" ] && [ -n "${PR:-}" ]; } || { echo "no token/PR; skip"; exit 0; }
-          icon() { case "$1" in success) printf '✅';; failure) printf '❌';; skipped) printf '⏭️';; *) printf '⚪';; esac; }
-          MARKER="<!-- ci-summary -->"
-          BODY="$(printf '%s\n## MCP Build & Validate\n\n- %s Build & validate (`%s` → `%s`)\n\n_Updated %s · [run](%s)_' \
-            "${MARKER}" \
-            "$(icon "${BUILD}")" "${HEAD_REF}" "${BASE_REF}" \
-            "$(date -u +%FT%TZ)" "${RUN_URL}")"
+          {
+            echo "## Wiki Update Reminder"
+            echo ""
+            echo "Docs are **wiki-first** at MokoConsulting. 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"
-          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
-            echo "updated sticky CI summary #${CID} on PR #${PR}"
-          else
-            curl -sf -X POST  -H "Authorization: token ${TOKEN}" -H "Content-Type: application/json" -d "${PAYLOAD}" "${LIST}" >/dev/null 2>&1 || true
-            echo "created sticky CI summary on PR #${PR}"
+          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)/' || 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-publish.yml

@@ -7,19 +7,14 @@
 # INGROUP: MokoCLI.Release
 # REPO: https://git.mokoconsulting.tech/MokoConsulting/Template-NPM
 # PATH: /.mokogit/workflows/npm-publish.yml
-# VERSION: 03.00.00
-# BRIEF: Build + publish shim. The shared release engine (pre-release.yml /
-#        auto-release.yml) owns version bump, tag, changelog and release
-#        object; this workflow only builds and publishes the version the
-#        engine has already written to package.json. It never bumps or
-#        writes the version. Build + publish now delegate to the centralized
-#        MokoCLI build agent (moko build / moko publish); `moko publish`
-#        preserves the same dual-registry npm publish (npmjs.org + the MokoGIT
-#        npm registry) that the former inline block performed.
-#
-# GATE: `moko` is provided by mokocli on the runner PATH (/opt/mokocli/cli),
-# available only after the mokocli build agent lands on `main` and the runner
-# image is rebuilt — authored/reviewed now, runs green later.
+# VERSION: 04.00.01
+# BRIEF: Build + publish shim. Version comes from the root Makefile
+#        (PROJECT_VERSION — the fleet-wide source of truth); this workflow never
+#        bumps it. It builds with plain npm and does an idempotent DUAL-REGISTRY
+#        publish: the MokoGIT npm registry using the per-run Actions token
+#        (GITHUB_TOKEN + packages:write — no shared MOKOGIT_TOKEN), and npmjs.org
+#        using NPM_TOKEN (best-effort; skipped if the secret is absent). A
+#        version already present on a registry is a no-op (idempotent).
 
 name: "Publish to npm"
 
@@ -29,125 +24,119 @@ on:
       - main
   workflow_dispatch:
 
+# The MokoGIT-registry publish uses the run's own token instead of a shared
+# org secret: least-privilege, auto-expiring, no per-repo provisioning.
+permissions:
+  contents: read
+  packages: write
+
+env:
+  MOKOGIT_HOST: git.mokoconsulting.tech
+
 jobs:
   publish:
+    name: "Build & dual-publish"
     runs-on: release
+    # Skip template repos, and self-pushes the release engine marks [skip ci]
+    # (its version-bump/changelog commits) or [skip publish].
     if: >-
+      !startsWith(github.event.repository.name, 'Template-') &&
       !contains(github.event.head_commit.message, '[skip ci]') &&
-      !contains(github.event.head_commit.message, '[skip publish]') &&
-      !startsWith(github.event.repository.name, 'Template-')
+      !contains(github.event.head_commit.message, '[skip publish]')
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          fetch-depth: 2
+          fetch-depth: 1
 
-      - name: Resolve source dir
-        id: srcdir
-        uses: ./.mokogit/actions/resolve-source-dir
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
-          mokogit_token: ${{ secrets.MOKOGIT_TOKEN }}
-          strict: 'true'
+          node-version: '20'
 
-      - name: Detect publishable changes
-        id: detect
+      - name: Resolve version from the Makefile
+        id: v
         run: |
           set -euo pipefail
-
-          # workflow_dispatch has no diff base — always treat as changed.
-          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            echo "::notice::workflow_dispatch — forcing changed=true"
-            echo "changed=true" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          # Build the source-dir alternative from the resolved dir (escape ERE metachars).
-          # Class lists ] first and [ last to avoid a [. collating-symbol parse; the
-          # \\\\& replacement reaches sed as \\& = literal backslash + matched char.
-          SRC_DIR='${{ steps.srcdir.outputs.source_dir }}'
-          SRC_RE=$(printf '%s' "$SRC_DIR" | sed 's/[].^$*+?(){}|[]/\\\\&/g')
-          PATTERN="^(${SRC_RE}|package\.json$|package-lock\.json$|tsconfig\.json$|README\.md$)"
-          echo "Detect pattern: ${PATTERN}"
-
-          BEFORE="${{ github.event.before }}"
-          if [ -z "${BEFORE}" ] || ! git cat-file -e "${BEFORE}^{commit}" 2>/dev/null; then
-            BEFORE=$(git rev-parse HEAD^ 2>/dev/null || echo "")
-          fi
-          if [ -n "${BEFORE}" ]; then
-            FILES=$(git diff --name-only "${BEFORE}" HEAD)
-          else
-            FILES=$(git show --name-only --pretty=format: HEAD)
-          fi
-
-          if printf '%s\n' "${FILES}" | grep -Eq "${PATTERN}"; then
-            echo "changed=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "::notice::No publishable changes under '${SRC_DIR}'. Files: ${FILES}"
-            echo "changed=false" >> "$GITHUB_OUTPUT"
+          # PROJECT_VERSION in the root Makefile is the single source of truth
+          # (auto-filled per repo by workflow sync). Everything else derives from it.
+          VERSION=$(grep -E '^[[:space:]]*PROJECT_VERSION[[:space:]]*:?=' Makefile | head -1 | sed 's/.*=[[:space:]]*//' | tr -d '[:space:]')
+          if [ -z "$VERSION" ]; then
+            echo "::error::No PROJECT_VERSION found in Makefile — cannot determine publish version."; exit 1
           fi
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          # Stamp package.json to match, IN-TREE ONLY (never committed) so `npm publish`
+          # ships exactly the Makefile version regardless of any package.json drift.
+          npm version "${VERSION}" --no-git-tag-version --allow-same-version >/dev/null 2>&1 || \
+            echo "::warning::could not stamp package.json to ${VERSION} (continuing)"
+          echo "Publishing version ${VERSION} (source: Makefile PROJECT_VERSION)"
 
-      - name: Setup Node.js
-        if: steps.detect.outputs.changed == 'true'
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
+      - name: Install & build
+        run: |
+          set -euo pipefail
+          npm ci --no-audit --no-fund || npm install --no-audit --no-fund
+          npm run build --if-present
 
-      - name: Setup MokoCLI build agent (moko on PATH)
-        if: steps.detect.outputs.changed == 'true'
+      - name: Publish to the MokoGIT npm registry (per-run Actions token)
         env:
-          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGIT_TOKEN }}
-          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
+          # The run's own Gitea Actions token; packages:write is granted above.
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          # Reach mokocli the SAME way the release workflows' "Setup MokoCLI tools"
-          # step does: prefer the pre-installed /opt/mokocli, else a fresh clone. We
-          # expose the `moko` binary on PATH so `moko build|publish` resolve — no new
-          # install mechanism is introduced.
-          if [ -x /opt/mokocli/cli/moko ] || [ -f /opt/mokocli/cli/moko ]; then
-            echo Using pre-installed /opt/mokocli
-            echo "/opt/mokocli/cli" >> "$GITHUB_PATH"
+          set -euo pipefail
+          OWNER='${{ github.repository_owner }}'
+          REG="https://${MOKOGIT_HOST}/api/packages/${OWNER}/npm/"
+          printf '//%s/api/packages/%s/npm/:_authToken=%s\n' "${MOKOGIT_HOST}" "${OWNER}" "${NODE_AUTH_TOKEN}" > .npmrc
+          # Capture output so we can tell a benign "already published" apart from a
+          # real failure (auth, network) — the latter MUST fail the run, not hide
+          # behind a warning. `set +e` so a non-zero exit doesn't kill the step
+          # before we classify it.
+          set +e
+          out="$(npm publish --registry "${REG}" 2>&1)"; rc=$?
+          set -e
+          rm -f .npmrc
+          echo "$out"
+          if [ "$rc" -eq 0 ]; then
+            echo "Published ${{ steps.v.outputs.version }} to the MokoGIT registry."
+          elif printf '%s' "$out" | grep -qiE 'cannot publish over|already exists|EPUBLISHCONFLICT|409 Conflict'; then
+            echo "::notice::MokoGIT registry already has ${{ steps.v.outputs.version }} — no-op (idempotent)."
           else
-            echo Falling back to fresh 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::MOKOGIT_TOKEN secret is empty — cannot clone mokocli fallback." >&2
-              exit 1
-            fi
-            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
-            CLONE_URL="https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/mokocli.git"
-            git clone --depth 1 --branch main --quiet "${CLONE_URL}" /tmp/mokocli
-            ( cd /tmp/mokocli && composer install --no-dev --no-interaction --no-progress --optimize-autoloader --quiet )
-            echo "/tmp/mokocli/cli" >> "$GITHUB_PATH"
+            echo "::error::MokoGIT-registry publish FAILED (npm exit ${rc}) — this is NOT 'already published'. See the npm error above (e.g. E401 = the Actions token was rejected)."
+            exit "$rc"
           fi
 
-      - name: Build
-        if: steps.detect.outputs.changed == 'true'
-        run: moko build
-
-      - name: Read version to publish
-        id: version
-        if: steps.detect.outputs.changed == 'true'
+      - name: Publish to npmjs.org (NPM_TOKEN, best-effort)
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
           set -euo pipefail
-          # READ-ONLY. The shared release engine (pre-release.yml / auto-release.yml)
-          # has already bumped and written this version into package.json and created
-          # the tag + release object. This shim only publishes it — it never bumps or
-          # writes the version.
-          VERSION=$(node -p "require('./package.json').version")
-          echo "Publishing version ${VERSION} (set by the shared release engine)."
-          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          if [ -z "${NPM_TOKEN:-}" ]; then
+            echo "::notice::NPM_TOKEN not set — skipping the public npmjs.org publish (MokoGIT registry is the primary)."
+            exit 0
+          fi
+          printf '//registry.npmjs.org/:_authToken=%s\n' "${NPM_TOKEN}" > .npmrc
+          # npmjs.org is the best-effort secondary (MokoGIT registry is primary),
+          # so a real failure warns loudly but does not fail the run — yet we still
+          # distinguish "already published" (expected) from "token invalid" (needs
+          # attention) instead of collapsing both into one vague message.
+          set +e
+          out="$(npm publish --registry https://registry.npmjs.org/ --access public 2>&1)"; rc=$?
+          set -e
+          rm -f .npmrc
+          echo "$out"
+          if [ "$rc" -eq 0 ]; then
+            echo "Published ${{ steps.v.outputs.version }} to npmjs.org."
+          elif printf '%s' "$out" | grep -qiE 'cannot publish over|already exists|EPUBLISHCONFLICT|409 Conflict'; then
+            echo "::notice::npmjs.org already has ${{ steps.v.outputs.version }} — no-op."
+          else
+            echo "::warning::npmjs.org publish failed (npm exit ${rc}) — token likely invalid/expired. Secondary registry only; not failing the run. See npm error above."
+          fi
 
-      - name: Publish to npmjs.org + git.mokoconsulting.tech
-        if: steps.detect.outputs.changed == 'true'
+      - name: Summary
+        if: always()
         run: |
-          # moko publish preserves the former inline behavior: idempotent dual-registry
-          # npm publish to npmjs.org AND the MokoGIT npm registry, publishing the version
-          # the release engine already wrote to package.json (never bumps). It reads the
-          # registry auth tokens from the environment below.
-          moko publish
-        env:
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-          MOKOGIT_TOKEN: ${{ secrets.MOKOGIT_TOKEN }}
+          {
+            echo "## npm publish — ${{ steps.v.outputs.version }}"
+            echo "- Version source: root \`Makefile\` PROJECT_VERSION"
+            echo "- MokoGIT registry: per-run Actions token (\`packages: write\`)"
+            echo "- npmjs.org: \`NPM_TOKEN\` (best-effort)"
+          } >> "$GITHUB_STEP_SUMMARY"