@mokoconsulting/mokogit-mcp 1.13.3 → 1.14.0

package/.mokogit/workflows/auto-release.yml

@@ -7,8 +7,8 @@
 # INGROUP: MokoCLI.Release
 # REPO: https://git.mokoconsulting.tech/MokoConsulting/Template-Generic
 # PATH: /.mokogit/workflows/auto-release.yml
-# VERSION: 07.23.00
-# BRIEF: NEW (07.23.00): "Vendor PHP dependencies (build-time)" added to BOTH publish legs (promote-rc + stable) — this workflow had NO build-time composer vendoring at all, so any component declaring runtime PHP deps via a sub-package composer.json (vendor-dir admin/vendor, e.g. mPDF in MokonyxCRM/MokonyxCRMDCM) shipped its rc/stable zip WITHOUT admin/vendor while the component manifest lists <folder>vendor</folder> — JInstaller then aborts the ENTIRE package install on-site ("File does not exist [ROOT][TMP]/.../admin/vendor" → "Failed to copy administrator files"). The step mirrors pre-release.yml 07.15.00: no-op without a sub-package composer.json; provisions ext-gd when missing (the release runners' php-cli lacks it, which failed mpdf dependency RESOLUTION outright); verifies the CONFIGURED vendor-dir (composer config vendor-dir) materialized autoload.php; FAILS the build loud when vendoring fails for a package whose manifest ships <folder>vendor</folder> (a green build with an install-bricking artifact is strictly worse than a red build); fail-soft warning for packages whose manifests do not reference vendor/. Runs before `moko publish` (release_publish.php → release_package.php zips the plain working tree; vendor/ was never excluded — the tree simply never had it in CI). PREVIOUS (07.22.00): #498 — the #469 SRC_DIR gate no longer self-traps, and the fast-merge guard is MINOR-identity aware (fixes stable version never advancing; MokoCLI stuck re-publishing v10.20.00). (1) The gate read SRC_DIR with grep|sed, capturing the LITERAL unexpanded `$(shell …)` from the fleet-standard `SRC_DIR := $(shell [ -d src ] && echo src || echo source)` — an unmatchable directory that forced should_bump=false on EVERY push even when source changed. It now resolves SRC_DIR via `make --eval` expansion, falls back to the grep|sed read only if make is unavailable, nulls out a still-unexpanded `$(...)`/backtick value, and treats a declared-but-NONEXISTENT SRC_DIR (repos with code in cli/lib/bin, not src/source) as the non-source denylist fallback instead of an unmatchable INCLUSION prefix. (2) The "Guarantee monotonic release version (fast-merge bump guard)" compared the FULL version, so dev's per-merge PATCH bumps (10.20.00→10.20.04) fooled it into "normal path, no heal" and it re-published the already-released vMAJOR.MINOR.00. It now compares the MINOR identity (MAJOR.MINOR), so a fast dev→stable merge with no promote-rc cuts a new MINOR. Fleet-wide release-semantics change — validate on one repo before syncing. PREVIOUS (07.21.00): #469 — gate the version BUMP on whether the push touched the Makefile SRC_DIR. The former non-code paths-ignore denylist on the push trigger is REMOVED: a docs/workflow/sample push no longer skips the pipeline, it now RUNS in no-bump "update the existing stable release in place" mode (re-stamps the UNCHANGED current version via the existing `moko publish --bump none --no-commit`, refreshes notes/assets, no version advance, no new vNN tag). A new early step "Resolve SRC_DIR bump gate (#469)" (id: srcgate) decides should_bump: (1) ELECTRON (file-detected) or opt-out vars.RELEASE_SRCDIR_GATE=off -> BYPASS, always bump as today (electron has NO source dir, so a naive SRC_DIR test would never bump — a release-breaking trap); (2) else SRC_DIR is REQUIRED — a non-electron repo with no resolvable SRC_DIR FAILS LOUD (::error:: + exit 1), never silently never-bump; (3) else diff the push range (github.event.before..GITHUB_SHA, with a HEAD^1 / merge-base fallback) intersected with ${SRC_DIR}/ — source hit -> should_bump=true, none -> should_bump=false. workflow_dispatch always bumps. The self-heal monotonic bump + the new vNN semver tag are now gated on should_bump!='false' so no-bump mode keeps the version PUT; the publish + "Update release notes and reconcile changelog" (channel-pointer resolution) run on BOTH paths to refresh the current release. Loop-safety is unchanged: the job if: still re-checks [skip ci]/[skip sync], so the workflow's own commits never re-trigger. Fleet-wide release-semantics change — validate on one repo before syncing. PREVIOUS (07.20.00): the dev/promote bump + release steps now name the per-run token env var GITHUB_TOKEN (was the misleadingly-named MOKOGIT_TOKEN; the VALUE was always ${{ github.token }}). All token use in this workflow is SAME-REPO (release API, the release_bump_dev dev base bump, pushes to its own repo) — the org MOKOGIT_TOKEN secret is not referenced here. Naming-only; no behavior change. Mirrors the pre-release.yml fix (MokoGIT#1721). PREVIOUS: NEW (07.19.00): #1621 Phase 6 / .mokogit-private#76 — resolve the CURRENT stable release by its CHANNEL POINTER, not by a fixed tag_name=stable. Under version-primary releases (a release is born with the immutable tag_name=vNN and `stable`/`rc` attached as movable is_channel tags), GET /releases/tags/stable no longer resolves the current stable release, which would break two steps that read "the last released version". Both now call GET /repos/{owner}/{repo}/releases/channel/stable (#1702 — resolves whichever release the `stable` channel points at via ReleaseStreamMap) with a GRACEFUL FALLBACK to the legacy GET /releases/tags/stable for forges predating #1702 (the channel route 404s pre-rollout and the rolling `stable` tag still exists). (1) The monotonic-version guard ("Guarantee monotonic release version") resolves ROLLING_LAST by parsing the same `VERSION: NN.NN.NN` out of the channel-resolved release NAME. (2) "Update release notes and reconcile changelog" resolves the stable RELEASE_ID + VERSION the same channel-first way. The #386 integrity gate is UNCHANGED (it already keys off the immutable vNN version tag). SEQUENCING unchanged: do NOT enable in prod until #1702 server support is on stable/prod; works pre-#1702 via the fallback. PREVIOUS (07.18.00): #1621 Phase 6 — version/* BRANCHES retired in favor of dual-tagged version RELEASES. REMOVED three now-redundant steps: "Step 12: Create version branch from main", "Step 13: Prune superseded-major version branches", and "Advance rolling channel tag via git". A release's permanent version identity is now the git tag v<version>, attached by the publish as a MOVABLE channel tag on the dual-tagged release (MokoCLI release_publish -> release_create channel_tags[]/update_stream; the forge attaches/moves the tag at the release commit via AttachChannelTag server-side) — so a new cut is born dual-tagged (rolling `stable`/`release-candidate` primary tag + permanent v<version> channel tag) and the channel tag MOVES onto the new release instead of a new version/* branch being created. The rolling `stable` tag is still pinned by release_create forceTagRef() (#808), so the "Advance rolling channel tag" force-push was redundant. KEPT UNCHANGED: "Create semver tag" (v<version>), the #386 integrity gate (still resolves tags/stable to the built commit), and the monotonic guard (still reads the stable release name VERSION: NN.NN.NN). Pruning EXISTING version/* branches is a SEPARATE one-time manual reconcile — not done here. SEQUENCING: do NOT enable in prod until the #1621 SERVER channel_tags support is on stable/prod. PREVIOUS (07.17.00): Setup MokoCLI tools no longer installs a STALE mokocli during the registry publish-lag window (#1671). After the fresh registry install, the step now compares the installed /tmp/mokocli PROJECT_VERSION against the /opt/mokocli failsafe and PREFERS whichever is NEWER (sort -V), and the opportunistic /opt refresh is gated to only move FORWARD (never downgrade /opt when it is the newer, just-deployed copy). Backward-compatible: runners with no /opt/mokocli use the registry copy exactly as before. PREVIOUS (07.16.00): release-integrity + dev-channel fixes. (1) A new pre-publish "no stale (pre-merge) tree" guard (#428/MokoCLI#901) hard-FAILS the release if the triggering GITHUB_SHA is an ANCESTOR of the current branch tip (a concurrent merge landed mid-run) -- otherwise a green, version-bumped release silently ships old code missing that merge (reproduced: built ef8c1a5d while tip was 2740342). Fail-open on any unresolved/replica-lagged tip so a good release is never falsely blocked. Complements the mokocli engine assertion (packaged-tree == GITHUB_SHA), which cannot see that GITHUB_SHA itself trails the tip. (2) The "Post-release: Reset dev version" safety-net (#309/MokoCLI#900) no longer swallows failure: a failed dev-advance now emits ::error:: + a job-summary block (dev-channel would trail stable), and a SUCCESSFUL advance dispatches pre-release.yml (development) to actually publish the leading dev build -- the advance commit is [skip ci]+paths-ignored and never auto-fires. Stays green (continue-on-error) since stable already published. NEW (07.15.00): the rolling stable channel tag is now advanced via a git force-push BEFORE the #386 integrity gate. MokoGIT's tags API 405s on the release-attached `stable` tag, so release_publish.php could not move it ("Could not pin tag stable ... HTTP 405") and every Joomla/electron stable cut left the tag lagging the freshly-built commit -- red-failing a correct release on the integrity gate. A new step git-force-pushes refs/tags/stable to the built HEAD (force-push allowlist -- the same escape hatch the rc BRANCH pin already uses), so the gate passes and no manual tag repoint is needed. PREVIOUS (07.14.00): integrity gate #386 no longer false-fails. It compared the published tag against GITHUB_SHA (the triggering commit), but the publish step commits the CHANGELOG entry ("build NN.NN.NN [skip ci]") and mokocli pins the channel tag + semver tag to that POST-PUBLISH HEAD -- so every cut whose CHANGELOG wasn't pre-seeded on dev (e.g. a version set straight on the release branch) diverged by one commit and red-failed a correct release. The gate now compares against the actual built/published HEAD (git rev-parse HEAD, falling back to GITHUB_SHA), which equals what the tag is pinned to in both the commit and no-commit cases while still catching a tag pinned to a commit we did NOT build; the semver tag is pinned to the same built HEAD for consistency. PREVIOUS (07.13.00): RC is ON-DEMAND ONLY. The `pull_request` trigger (RC-preview on a PR to main/stable) is REMOVED and the promote-rc job now runs solely on workflow_dispatch action=promote-rc. Only dev + stable release automatically (dev via pre-release.yml push->dev; stable via the push->main release job here); alpha/beta/rc never auto-cut. PREVIOUS (07.12.00): electron repos create NO release on ANY channel (RC enabled=false + stable publish/tag/notes/integrity guarded on is_electron; opt back in with vars.ELECTRON_CI_BUILD=true) and build NO installer in CI — always built locally + uploaded manually; the dev/promote version BUMP still runs. Template-Generic #390. NEW (07.11.00): the electron installer build/attach steps (electron-builder via Wine/Xvfb) are gated to MANUAL workflow_dispatch only (`&& github.event_name == 'workflow_dispatch'`). An automatic push no longer auto-builds electron installers (heavy ~90m, runner-fragile — OOM/Wine-zombie; migrating to mokocli ElectronPackager, MokoCLI #756/#758). The version bump, CHANGELOG, tag and npm publish STILL run on push — only the electron installer is skipped and pushed MANUALLY via dispatch. Non-electron platforms (joomla/go/npm) unaffected. Template-Generic #390. Universal build & release - BUMP-ON-DEV: base version + CHANGELOG promoted on dev pre-promotion (promote-rc), main publishes --bump none --no-commit so it never diverges from dev. MokoCLI build agent (moko publish). NEW (07.06.00): npm stable publishing ABSORBED here from Template-NPM's retired npm-publish.yml as npm-gated dual-registry steps (MokoGIT registry via per-run token + npmjs.org best-effort), replacing the former npm-publish.yml dispatch. No-Makefile repos SKIP the release job gracefully (green) instead of failing. Conflict-marker scan reads git-tracked files only (git ls-files | xargs grep) so vendored/generated trees can't false-match. NEW (07.07.00): npm stamp normalizes the zero-padded Makefile PROJECT_VERSION (NN.NN.NN) to strict semver via awk before `npm version`, and an unstampable version now HARD-FAILS instead of silently keeping the old package.json version (#382). NEW (07.00.00): `moko assets:optimize` artifact-time step added before publish (graceful-skip on non-asset repos); Setup MokoCLI tools makes the fresh `moko` executable + first on PATH to fix exit-126 (mokocli #650).
+# VERSION: 07.24.00
+# BRIEF: NEW (07.24.00): npmjs.org publish now FAILS LOUD (::error:: + exit $rc) on an AUTHORIZATION error (404 "not in this registry" / 401 / 403 / ENEEDAUTH / EOTP) instead of swallowing EVERY failure as a non-failing ::warning:: — a missing-scope / unauthorized / revoked / expired NPM_TOKEN previously hid behind a green release fleet-wide (the "secondary registry, not failing the run" catch masked a 404 PUT, which is exactly how npm reports an unauthorized scoped write; CI had in fact NEVER successfully published any MCP package to npmjs while every run reported success). Transient/5xx/network failures still stay a non-failing ::warning:: (npmjs is the SECONDARY mirror; the MokoGIT registry is primary and already hard-fails), and an unset NPM_TOKEN still skips cleanly — so repos that do not publish to npmjs are 100% unaffected. PREVIOUS (07.23.00): "Vendor PHP dependencies (build-time)" added to BOTH publish legs (promote-rc + stable) — this workflow had NO build-time composer vendoring at all, so any component declaring runtime PHP deps via a sub-package composer.json (vendor-dir admin/vendor, e.g. mPDF in MokonyxCRM/MokonyxCRMDCM) shipped its rc/stable zip WITHOUT admin/vendor while the component manifest lists <folder>vendor</folder> — JInstaller then aborts the ENTIRE package install on-site ("File does not exist [ROOT][TMP]/.../admin/vendor" → "Failed to copy administrator files"). The step mirrors pre-release.yml 07.15.00: no-op without a sub-package composer.json; provisions ext-gd when missing (the release runners' php-cli lacks it, which failed mpdf dependency RESOLUTION outright); verifies the CONFIGURED vendor-dir (composer config vendor-dir) materialized autoload.php; FAILS the build loud when vendoring fails for a package whose manifest ships <folder>vendor</folder> (a green build with an install-bricking artifact is strictly worse than a red build); fail-soft warning for packages whose manifests do not reference vendor/. Runs before `moko publish` (release_publish.php → release_package.php zips the plain working tree; vendor/ was never excluded — the tree simply never had it in CI). PREVIOUS (07.22.00): #498 — the #469 SRC_DIR gate no longer self-traps, and the fast-merge guard is MINOR-identity aware (fixes stable version never advancing; MokoCLI stuck re-publishing v10.20.00). (1) The gate read SRC_DIR with grep|sed, capturing the LITERAL unexpanded `$(shell …)` from the fleet-standard `SRC_DIR := $(shell [ -d src ] && echo src || echo source)` — an unmatchable directory that forced should_bump=false on EVERY push even when source changed. It now resolves SRC_DIR via `make --eval` expansion, falls back to the grep|sed read only if make is unavailable, nulls out a still-unexpanded `$(...)`/backtick value, and treats a declared-but-NONEXISTENT SRC_DIR (repos with code in cli/lib/bin, not src/source) as the non-source denylist fallback instead of an unmatchable INCLUSION prefix. (2) The "Guarantee monotonic release version (fast-merge bump guard)" compared the FULL version, so dev's per-merge PATCH bumps (10.20.00→10.20.04) fooled it into "normal path, no heal" and it re-published the already-released vMAJOR.MINOR.00. It now compares the MINOR identity (MAJOR.MINOR), so a fast dev→stable merge with no promote-rc cuts a new MINOR. Fleet-wide release-semantics change — validate on one repo before syncing. PREVIOUS (07.21.00): #469 — gate the version BUMP on whether the push touched the Makefile SRC_DIR. The former non-code paths-ignore denylist on the push trigger is REMOVED: a docs/workflow/sample push no longer skips the pipeline, it now RUNS in no-bump "update the existing stable release in place" mode (re-stamps the UNCHANGED current version via the existing `moko publish --bump none --no-commit`, refreshes notes/assets, no version advance, no new vNN tag). A new early step "Resolve SRC_DIR bump gate (#469)" (id: srcgate) decides should_bump: (1) ELECTRON (file-detected) or opt-out vars.RELEASE_SRCDIR_GATE=off -> BYPASS, always bump as today (electron has NO source dir, so a naive SRC_DIR test would never bump — a release-breaking trap); (2) else SRC_DIR is REQUIRED — a non-electron repo with no resolvable SRC_DIR FAILS LOUD (::error:: + exit 1), never silently never-bump; (3) else diff the push range (github.event.before..GITHUB_SHA, with a HEAD^1 / merge-base fallback) intersected with ${SRC_DIR}/ — source hit -> should_bump=true, none -> should_bump=false. workflow_dispatch always bumps. The self-heal monotonic bump + the new vNN semver tag are now gated on should_bump!='false' so no-bump mode keeps the version PUT; the publish + "Update release notes and reconcile changelog" (channel-pointer resolution) run on BOTH paths to refresh the current release. Loop-safety is unchanged: the job if: still re-checks [skip ci]/[skip sync], so the workflow's own commits never re-trigger. Fleet-wide release-semantics change — validate on one repo before syncing. PREVIOUS (07.20.00): the dev/promote bump + release steps now name the per-run token env var GITHUB_TOKEN (was the misleadingly-named MOKOGIT_TOKEN; the VALUE was always ${{ github.token }}). All token use in this workflow is SAME-REPO (release API, the release_bump_dev dev base bump, pushes to its own repo) — the org MOKOGIT_TOKEN secret is not referenced here. Naming-only; no behavior change. Mirrors the pre-release.yml fix (MokoGIT#1721). PREVIOUS: NEW (07.19.00): #1621 Phase 6 / .mokogit-private#76 — resolve the CURRENT stable release by its CHANNEL POINTER, not by a fixed tag_name=stable. Under version-primary releases (a release is born with the immutable tag_name=vNN and `stable`/`rc` attached as movable is_channel tags), GET /releases/tags/stable no longer resolves the current stable release, which would break two steps that read "the last released version". Both now call GET /repos/{owner}/{repo}/releases/channel/stable (#1702 — resolves whichever release the `stable` channel points at via ReleaseStreamMap) with a GRACEFUL FALLBACK to the legacy GET /releases/tags/stable for forges predating #1702 (the channel route 404s pre-rollout and the rolling `stable` tag still exists). (1) The monotonic-version guard ("Guarantee monotonic release version") resolves ROLLING_LAST by parsing the same `VERSION: NN.NN.NN` out of the channel-resolved release NAME. (2) "Update release notes and reconcile changelog" resolves the stable RELEASE_ID + VERSION the same channel-first way. The #386 integrity gate is UNCHANGED (it already keys off the immutable vNN version tag). SEQUENCING unchanged: do NOT enable in prod until #1702 server support is on stable/prod; works pre-#1702 via the fallback. PREVIOUS (07.18.00): #1621 Phase 6 — version/* BRANCHES retired in favor of dual-tagged version RELEASES. REMOVED three now-redundant steps: "Step 12: Create version branch from main", "Step 13: Prune superseded-major version branches", and "Advance rolling channel tag via git". A release's permanent version identity is now the git tag v<version>, attached by the publish as a MOVABLE channel tag on the dual-tagged release (MokoCLI release_publish -> release_create channel_tags[]/update_stream; the forge attaches/moves the tag at the release commit via AttachChannelTag server-side) — so a new cut is born dual-tagged (rolling `stable`/`release-candidate` primary tag + permanent v<version> channel tag) and the channel tag MOVES onto the new release instead of a new version/* branch being created. The rolling `stable` tag is still pinned by release_create forceTagRef() (#808), so the "Advance rolling channel tag" force-push was redundant. KEPT UNCHANGED: "Create semver tag" (v<version>), the #386 integrity gate (still resolves tags/stable to the built commit), and the monotonic guard (still reads the stable release name VERSION: NN.NN.NN). Pruning EXISTING version/* branches is a SEPARATE one-time manual reconcile — not done here. SEQUENCING: do NOT enable in prod until the #1621 SERVER channel_tags support is on stable/prod. PREVIOUS (07.17.00): Setup MokoCLI tools no longer installs a STALE mokocli during the registry publish-lag window (#1671). After the fresh registry install, the step now compares the installed /tmp/mokocli PROJECT_VERSION against the /opt/mokocli failsafe and PREFERS whichever is NEWER (sort -V), and the opportunistic /opt refresh is gated to only move FORWARD (never downgrade /opt when it is the newer, just-deployed copy). Backward-compatible: runners with no /opt/mokocli use the registry copy exactly as before. PREVIOUS (07.16.00): release-integrity + dev-channel fixes. (1) A new pre-publish "no stale (pre-merge) tree" guard (#428/MokoCLI#901) hard-FAILS the release if the triggering GITHUB_SHA is an ANCESTOR of the current branch tip (a concurrent merge landed mid-run) -- otherwise a green, version-bumped release silently ships old code missing that merge (reproduced: built ef8c1a5d while tip was 2740342). Fail-open on any unresolved/replica-lagged tip so a good release is never falsely blocked. Complements the mokocli engine assertion (packaged-tree == GITHUB_SHA), which cannot see that GITHUB_SHA itself trails the tip. (2) The "Post-release: Reset dev version" safety-net (#309/MokoCLI#900) no longer swallows failure: a failed dev-advance now emits ::error:: + a job-summary block (dev-channel would trail stable), and a SUCCESSFUL advance dispatches pre-release.yml (development) to actually publish the leading dev build -- the advance commit is [skip ci]+paths-ignored and never auto-fires. Stays green (continue-on-error) since stable already published. NEW (07.15.00): the rolling stable channel tag is now advanced via a git force-push BEFORE the #386 integrity gate. MokoGIT's tags API 405s on the release-attached `stable` tag, so release_publish.php could not move it ("Could not pin tag stable ... HTTP 405") and every Joomla/electron stable cut left the tag lagging the freshly-built commit -- red-failing a correct release on the integrity gate. A new step git-force-pushes refs/tags/stable to the built HEAD (force-push allowlist -- the same escape hatch the rc BRANCH pin already uses), so the gate passes and no manual tag repoint is needed. PREVIOUS (07.14.00): integrity gate #386 no longer false-fails. It compared the published tag against GITHUB_SHA (the triggering commit), but the publish step commits the CHANGELOG entry ("build NN.NN.NN [skip ci]") and mokocli pins the channel tag + semver tag to that POST-PUBLISH HEAD -- so every cut whose CHANGELOG wasn't pre-seeded on dev (e.g. a version set straight on the release branch) diverged by one commit and red-failed a correct release. The gate now compares against the actual built/published HEAD (git rev-parse HEAD, falling back to GITHUB_SHA), which equals what the tag is pinned to in both the commit and no-commit cases while still catching a tag pinned to a commit we did NOT build; the semver tag is pinned to the same built HEAD for consistency. PREVIOUS (07.13.00): RC is ON-DEMAND ONLY. The `pull_request` trigger (RC-preview on a PR to main/stable) is REMOVED and the promote-rc job now runs solely on workflow_dispatch action=promote-rc. Only dev + stable release automatically (dev via pre-release.yml push->dev; stable via the push->main release job here); alpha/beta/rc never auto-cut. PREVIOUS (07.12.00): electron repos create NO release on ANY channel (RC enabled=false + stable publish/tag/notes/integrity guarded on is_electron; opt back in with vars.ELECTRON_CI_BUILD=true) and build NO installer in CI — always built locally + uploaded manually; the dev/promote version BUMP still runs. Template-Generic #390. NEW (07.11.00): the electron installer build/attach steps (electron-builder via Wine/Xvfb) are gated to MANUAL workflow_dispatch only (`&& github.event_name == 'workflow_dispatch'`). An automatic push no longer auto-builds electron installers (heavy ~90m, runner-fragile — OOM/Wine-zombie; migrating to mokocli ElectronPackager, MokoCLI #756/#758). The version bump, CHANGELOG, tag and npm publish STILL run on push — only the electron installer is skipped and pushed MANUALLY via dispatch. Non-electron platforms (joomla/go/npm) unaffected. Template-Generic #390. Universal build & release - BUMP-ON-DEV: base version + CHANGELOG promoted on dev pre-promotion (promote-rc), main publishes --bump none --no-commit so it never diverges from dev. MokoCLI build agent (moko publish). NEW (07.06.00): npm stable publishing ABSORBED here from Template-NPM's retired npm-publish.yml as npm-gated dual-registry steps (MokoGIT registry via per-run token + npmjs.org best-effort), replacing the former npm-publish.yml dispatch. No-Makefile repos SKIP the release job gracefully (green) instead of failing. Conflict-marker scan reads git-tracked files only (git ls-files | xargs grep) so vendored/generated trees can't false-match. NEW (07.07.00): npm stamp normalizes the zero-padded Makefile PROJECT_VERSION (NN.NN.NN) to strict semver via awk before `npm version`, and an unstampable version now HARD-FAILS instead of silently keeping the old package.json version (#382). NEW (07.00.00): `moko assets:optimize` artifact-time step added before publish (graceful-skip on non-asset repos); Setup MokoCLI tools makes the fresh `moko` executable + first on PATH to fix exit-126 (mokocli #650).
 #
 # +=======================================================================+
 # |              UNIVERSAL BUILD & RELEASE PIPELINE                        |
@@ -1676,7 +1676,8 @@ jobs:
           rm -f .npmrc; echo "$out"
           if [ "$rc" -eq 0 ]; then echo "Published to npmjs.org."
           elif printf '%s' "$out" | grep -qiE 'already exists|cannot publish over|EPUBLISHCONFLICT|409 Conflict'; then echo "::notice::npmjs.org already has this version - no-op."
-          else echo "::warning::npmjs.org publish failed (npm exit ${rc}) - secondary registry only, not failing the run."; fi
+          elif printf '%s' "$out" | grep -qiE 'not in this registry|ENEEDAUTH|EOTP|need auth|E401|E403|401 Unauthorized|403 Forbidden|404 Not Found|Forbidden'; then echo "::error::npmjs.org publish FAILED — authorization error (npm exit ${rc}). NPM_TOKEN lacks publish/create rights on the @mokoconsulting scope (new-scoped-name first publish, an unauthorized token, or a revoked/expired token). Failing loud so a broken publish token cannot hide behind a green release — a 404 PUT is how npm masks an unauthorized scoped write."; exit "$rc"
+          else echo "::warning::npmjs.org publish failed (npm exit ${rc}) — transient/5xx/network issue; npmjs is the secondary mirror (MokoGIT registry is primary), not failing the run."; fi
 
       # GitHub mirroring (release assets + main branch) moved to an out-of-band
       # OAuth push-mirror (Gitea repo setting) -- former Steps 9 & 10 removed.

package/CHANGELOG.md

@@ -21,7 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - **`git_org_sync_profile_apply` now polls to completion by default (#264).** The generated tool fired the `POST .../sync-profiles/{id}/sync` once and returned. The server applies in **batches**, so on a large profile (observed: 79 targets / 209 pending changes) a single call only advanced part way (209→54) and the operator had to manually re-invoke apply and watch `git_org_sync_profile_status` until it hit 0 — and a big batch could exceed the client's 30s timeout, surfacing as a hard failure while the server kept working in the background. A hand-written override (registered ahead of the generated registration, so the existing collision guard skips the generated name) now **apply → status → repeat** until `in_sync`, a stall (pending stops decreasing across 2 rounds), or a 10-round safety cap. An apply-round **timeout is treated as "still running"** — swallowed, then status is polled to observe real progress and the loop continues. Returns a structured result: per-round `pending_trajectory` (e.g. `[209,54,0]`), `rounds`, final `{in_sync, pending_changes, target_count}`, the merged `applied_target_repo_ids`, and a `stop_reason`. New optional **`wait`** param (default `true` = polling); `wait:false` restores the old single-shot apply. Backward compatible — existing callers get the completion behavior automatically.
 
-## [1.13.0] --- 2026-10-28
+## [1.13.0] --- 2026-10-29
 
 ### Added
 - **Channel-name tag/branch collision guardrail on ref-resolving read tools (#236).** MokoGIT's release model uses channel-named rolling tags (`stable`, `dev`, `rc`, …) that are force-advanced to each build, so on channel-named-branch repos a git **tag and branch can share a name**. Git's bare-ref precedence resolves the name to the **tag before the branch**, so a tool handed a bare channel name silently returned the tag's content. Twelve ref-taking read tools (`file_get`, `dir_get`, `tree_get`, `commits_list`, `compare`, `ref_statuses_list`, `status_combined_get`, `repo_raw_get`, `repo_media_get`, `contents_ext_get`, `contents_list`, `file_contents_get`) now probe, **in parallel with the real request**, whether the ref name exists as both `refs/heads/<name>` and `refs/tags/<name>` at **different** commits and, if so, prepend a non-fatal `⚠` warning naming both targets, which one git resolves to, and how to qualify explicitly. The guard is **fail-open** (any probe error returns no warning, never breaking the real call), skips already-qualified refs (`refs/…`, `heads/…`, `tags/…`) and SHA-looking inputs, and uses an **exact** `ref` match so Gitea's prefix matching can't false-positive. Verified end-to-end against the live `stable` collision on this repo.
@@ -35,6 +35,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Rapid-merge guard on `git_pull_merge` (#288).** Merging several PRs into the same base back-to-back fired one `pre-release.yml` per merge, and those runs raced to bump the base version files via the Contents API — the loser got HTTP 422 "sha does not match" on its `bot/version-advance/<base>-*` temp branch (0 files stamped, red run, duplicate/under-bumped versions; observed laddering 4 MokonyxInsight PRs into `dev`). The root cause is merge concurrency, so the guard sits at the merge layer: a new `source/rapid-merge-guard.ts` module (1) **serializes** merges to the same `(repo, base)` through an in-process async lock/queue so two `pull_merge` calls can't overlap; (2) **settle-waits** — detects an in-flight `pre-release.yml` (or any run writing `bot/version-advance/<base>-*`) on the base and holds until it completes (bounded by `max_wait`) before releasing the next merge, or applies a fixed cooldown; and (3) **reports** the wait + reason in the merge result (e.g. `held 42s for in-flight pre-release run #NNN on dev before merging`). New optional `git_pull_merge` params: `rapid_merge_guard` (`settle` (default) | `cooldown:<sec>` | `off`), `max_wait` (seconds, default 180), and `force` (bypass). Falls back to the `MOKOGIT_RAPID_MERGE_GUARD` / `MOKOGIT_RAPID_MERGE_MAX_WAIT` env vars then the defaults. **Fail-open**: a PR/runs lookup error merges unguarded rather than blocking. Complements #287 (pre-merge CI red gate), which edits the same handler — this prevents merges from *creating* the race; the deeper server-side retry-on-422 fix is tracked under MokoGIT #1721.
 
+- **`git_user_token_create` can now scope a token to specific repositories (#286).** The forge side (MokoGIT #1952, prod 02.85.00) extended `CreateAccessTokenOption` with `all_repos` and `repo_ids`, letting a personal access token be restricted to a chosen set of repositories instead of the implicit "all repos incl. future". The tool gains three optional params: **`all_repos`** (boolean — token covers all repos incl. future, forge default `true`), **`repo_ids`** (`number[]` — when `all_repos=false`, restrict to these repository IDs), and **`repos`** (`string[]` — convenience: repo full-names `owner/name` resolved to IDs client-side via `GET /repos/{owner}/{repo}` and merged into `repo_ids`). The forge field names sent on the body are `all_repos` and `repo_ids`. Backward compatible — omitting all three preserves the prior all-repos behavior. `git_user_tokens_list` is a raw passthrough and already surfaces the new response fields.
+- **MCP server version is now read from `package.json` instead of a hardcoded literal.** The `McpServer({ version })` constructor was pinned at `1.5.0`, long stale versus the real package version. It now resolves `package.json`'s `version` at runtime (`createRequire(import.meta.url)`), so the advertised server version tracks the Makefile `PROJECT_VERSION` / `package.json` source of truth automatically.
+
 ## [1.12.3] --- 2026-09-11
 
 ### Deprecated

package/CODE_OF_CONDUCT.md

@@ -14,7 +14,7 @@
 	DEFGROUP: 
 	INGROUP: Project.Documentation
 	REPO: MokoConsulting/mokogit-mcp
-	VERSION: 00.00.01
+	VERSION: 01.14.00
 	PATH: ./CODE_OF_CONDUCT.md
 	BRIEF: Contributor Covenant Code of Conduct version 1.3.0
 -->

package/CONTRIBUTING.md

@@ -14,7 +14,7 @@
 	DEFGROUP: 
 	INGROUP: Project.Documentation
 	REPO: https://git.mokoconsulting.tech/MokoConsulting/mokogit-mcp
-	VERSION: 00.00.01
+	VERSION: 01.14.00
 	PATH: ./CONTRIBUTING.md
 	BRIEF: Contribution guidelines for the project
 -->

package/Makefile

@@ -10,7 +10,7 @@
 # Identity (auto-filled by workflow sync — the Makefile is the version source of truth)
 # ==============================================================================
 PROJECT_NAME    := mcp-mokogit
-PROJECT_VERSION := 1.13.3
+PROJECT_VERSION := 01.14.00
 PLATFORM        := npm
 
 # ==============================================================================

package/config.example.json

@@ -1,13 +1,15 @@
 {
+	"//": "NO INLINE SECRETS. Point each connection at a token FILE via tokenFile. An inline \"token\" is legacy and is auto-migrated to ~/.ssh/tokens/<host>.token.json on first run (the config is rewritten and a .bak is kept). The token file may hold a raw PAT or a JSON blob {token|access_token, expires_*, scope(s), permissions}; Google service-account/OAuth creds are detected and refused (no token exchange).",
 	"defaultConnection": "moko",
 	"connections": {
 		"moko": {
 			"baseUrl": "https://git.mokoconsulting.tech",
-			"token": "your-git-access-token"
+			"tokenFile": "~/.ssh/tokens/git.mokoconsulting.tech.jmiller.token"
 		},
 		"github-mirror": {
 			"baseUrl": "https://git.example.com",
-			"token": "your-other-token"
+			"tokenFile": "~/.ssh/tokens/git.example.com.token",
+			"//token": "legacy: an inline \"token\": \"...\" here still works but is auto-migrated to a tokenFile on first run (no-inline-secrets policy)"
 		}
 	}
 }

package/dist/index.js

@@ -15,6 +15,7 @@
  */
 import * as https from 'node:https';
 import * as http from 'node:http';
+import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
@@ -23,6 +24,7 @@ import { GitClient } from './client.js';
 import { setGeneratedConfig, setGeneratedServer, setRegisteredNames, } from './generated-runtime.js';
 import { registerGeneratedToolsV2 } from './tools.generated.js';
 import { resolveGuardConfig, runGuardedMerge } from './rapid-merge-guard.js';
+import { probeBackends, warnBackendStatus, runMokoCli, cliRunEnabled, assertSafeArgs } from './mokocli.js';
 import { investigatePremergeCi, evaluatePremergeGate, renderPremergeReport, } from './premerge-ci.js';
 let config;
 function clientFor(connection) {
@@ -198,9 +200,13 @@ const OwnerRepo = {
     owner: z.string().describe('Repository owner (user or org)'),
     repo: z.string().describe('Repository name'),
 };
+// Resolve the real package version from package.json (single source of truth,
+// kept in sync with the Makefile PROJECT_VERSION) rather than a hardcoded string.
+const pkg = createRequire(import.meta.url)('../package.json');
+const SERVER_VERSION = pkg.version ?? '0.0.0';
 const server = new McpServer({
     name: 'mokogit-mcp',
-    version: '1.5.0',
+    version: SERVER_VERSION,
 });
 // ── Tool registration wrapper (Git → MokoGIT brand normalization) ────
 //
@@ -247,6 +253,44 @@ function registerTool(name, description, paramsSchema, cb) {
 }
 // ── User / Auth ─────────────────────────────────────────────────────────
 registerTool('git_me', 'Get the authenticated user info', { ...ConnectionParam }, async ({ connection }) => formatResponse(await clientFor(connection).get('/user')));
+// ── Operation backends: mokogit-cli (MokoCLI) — precedence api > mokogit-cli > git ──
+//
+// The REST API is the PRIMARY path: every other tool here calls it directly, and
+// that is what you should use for anything the API covers. The mokogit-cli binary
+// is a FALLBACK backend for CLI-only operations (or when the API is unavailable);
+// plain git is the last resort. These two tools expose that layer.
+registerTool('cli_status', 'Report the MokoGIT MCP operation backends and their precedence (api > mokogit-cli > git): which are available, the resolved mokogit-cli/git binary paths and versions, and the active backend. The REST API is always primary; mokogit-cli and git are fallbacks. Use this to check whether CLI-assisted operations are available on this host.', {}, async () => {
+    const status = await probeBackends();
+    return { content: [{ type: 'text', text: JSON.stringify(status, null, 2) }] };
+});
+registerTool('cli_run', 'Run a mokogit-cli (MokoCLI) subcommand as a FALLBACK backend and return its exit code, stdout and stderr. DISABLED by default — an operator must opt in with $MOKOGIT_ENABLE_CLI_RUN=1 (arbitrary CLI execution). Precedence is api > mokogit-cli > git — prefer the REST API tools for anything they cover; use this only for CLI-only operations or when the API is unavailable. Arguments are passed as argv (no shell); option-like args (leading "-") are rejected unless allowlisted or $MOKOGIT_CLI_ALLOW_FLAGS=1; any cwd must be inside $MOKOGIT_CLI_WORKDIR. Refuses with a clear message when disabled or when mokogit-cli is not installed (check cli_status).', {
+    args: z.array(z.string()).describe('mokogit-cli arguments as an argv array, e.g. ["version"] or ["repo","list"]. Passed directly to the binary (no shell).'),
+    cwd: z.string().optional().describe('Working directory — must resolve inside $MOKOGIT_CLI_WORKDIR (optional).'),
+    timeout_seconds: z.number().int().positive().max(600).optional().describe('Max run time in seconds (default 60).'),
+    input: z.string().optional().describe('Optional data to write to the CLI’s stdin.'),
+}, async ({ args, cwd, timeout_seconds, input }) => {
+    if (!cliRunEnabled()) {
+        return { content: [{ type: 'text', text: 'cli_run is disabled. Arbitrary mokogit-cli execution is an operator opt-in — set $MOKOGIT_ENABLE_CLI_RUN=1 to enable it. The REST API tools are the primary path (precedence api > mokogit-cli > git); use cli_status to see backend availability.' }] };
+    }
+    try {
+        assertSafeArgs(args);
+        const r = await runMokoCli(args, {
+            cwd,
+            timeoutMs: timeout_seconds ? timeout_seconds * 1000 : undefined,
+            input,
+        });
+        const text = [
+            `$ ${r.command}`,
+            `exit: ${r.code}${r.ok ? '' : ' (non-zero)'}`,
+            r.stdout ? `\n--- stdout ---\n${r.stdout.trimEnd()}` : '',
+            r.stderr ? `\n--- stderr ---\n${r.stderr.trimEnd()}` : '',
+        ].filter(Boolean).join('\n');
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: err instanceof Error ? err.message : String(err) }] };
+    }
+});
 registerTool('git_user_orgs', 'List organizations the authenticated user belongs to', { ...PaginationParams, ...ConnectionParam }, async ({ page, limit, connection }) => formatResponse(await clientFor(connection).get('/user/orgs', pageQuery({ page, limit }))));
 registerTool('git_user_repos', 'List repositories owned by the authenticated user', { ...PaginationParams, ...ConnectionParam }, async ({ page, limit, connection }) => formatResponse(await clientFor(connection).get('/user/repos', pageQuery({ page, limit }))));
 // ── Repository CRUD ─────────────────────────────────────────────────────
@@ -1432,7 +1476,7 @@ registerTool('git_repo_mirror_setup_github_backup', 'One-step GitHub backup mirr
     const client = clientFor(connection);
     const results = [];
     // 1. Try to create the GitHub repo via GitHub API
-    const ghRes = await fetch(`https://api.github.com/orgs/${ghOrg}/repos`, {
+    const ghRes = await fetch(`https://api.github.com/orgs/${enc(ghOrg)}/repos`, {
         method: 'POST',
         headers: {
             'Authorization': `Bearer ${ghToken}`,
@@ -1498,7 +1542,7 @@ registerTool('git_repo_mirror_setup_github_backup_full', 'Full GitHub backup: mi
     const syncInterval = interval ?? '8h0m0s';
     const results = [];
     // 1. Create GitHub repo (if needed)
-    const ghRes = await fetch(`https://api.github.com/orgs/${ghOrg}/repos`, {
+    const ghRes = await fetch(`https://api.github.com/orgs/${enc(ghOrg)}/repos`, {
         method: 'POST',
         headers: {
             'Authorization': `Bearer ${ghToken}`,
@@ -1526,7 +1570,7 @@ registerTool('git_repo_mirror_setup_github_backup_full', 'Full GitHub backup: mi
         return { content: [{ type: 'text', text: `GitHub repo creation failed (${ghRes.status}): ${JSON.stringify(ghData)}` }] };
     }
     // 2. Enable wiki on GitHub repo (in case it was disabled)
-    await fetch(`https://api.github.com/repos/${ghOrg}/${repo}`, {
+    await fetch(`https://api.github.com/repos/${enc(ghOrg)}/${enc(repo)}`, {
         method: 'PATCH',
         headers: {
             'Authorization': `Bearer ${ghToken}`,
@@ -1601,7 +1645,7 @@ registerTool('git_admin_cron_list', 'List cron tasks and their last run time (ad
 registerTool('git_admin_cron_run', 'Trigger a cron task (admin only)', {
     task: z.string().describe('Cron task name (e.g. "repo_health_check", "resync_all_hooks", "repo_archive_cleanup")'),
     ...ConnectionParam,
-}, async ({ task, connection }) => formatResponse(await clientFor(connection).post(`/admin/cron/${task}`, {})));
+}, async ({ task, connection }) => formatResponse(await clientFor(connection).post(`/admin/cron/${enc(task)}`, {})));
 // ── Generic API Call ────────────────────────────────────────────────────
 registerTool('git_api_request', 'Make a raw API request to any Git v1 endpoint', {
     method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).describe('HTTP method'),
@@ -2270,12 +2314,37 @@ registerTool('git_user_token_create', 'Create an access token for a user', {
     username: z.string().describe('Owner of the token (username in the path)'),
     name: z.string().describe('Name of the token'),
     scopes: z.array(z.string()).optional().describe('Token scopes (e.g. ["read:user", "write:repository"])'),
+    all_repos: z.boolean().optional().describe('Token covers all repos incl. future (default true)'),
+    repo_ids: z.array(z.number()).optional().describe('When all_repos=false, restrict to these repository IDs'),
+    repos: z.array(z.string()).optional().describe('Convenience: repo full-names (owner/name) resolved to IDs client-side'),
     ...ConnectionParam,
-}, async ({ username, name, scopes, connection }) => {
+}, async ({ username, name, scopes, all_repos, repo_ids, repos, connection }) => {
+    const client = clientFor(connection);
     const body = { name };
     if (scopes)
         body.scopes = scopes;
-    return formatResponse(await clientFor(connection).post(`/users/${enc(username)}/tokens`, body));
+    if (all_repos !== undefined)
+        body.all_repos = all_repos;
+    // Resolve any repo full-names (owner/name) to numeric IDs and merge with
+    // any explicit repo_ids. The forge expects the field name `repo_ids`.
+    const resolvedIds = Array.isArray(repo_ids) ? [...repo_ids] : [];
+    if (repos?.length) {
+        for (const full of repos) {
+            const slash = full.indexOf('/');
+            if (slash < 0)
+                throw new Error(`repos entries must be "owner/name": got "${full}"`);
+            const ownerPart = full.slice(0, slash);
+            const repoPart = full.slice(slash + 1);
+            const res = await client.get(`/repos/${enc(ownerPart)}/${enc(repoPart)}`);
+            const id = res.data?.id;
+            if (typeof id !== 'number')
+                throw new Error(`Could not resolve repository id for "${full}" (status ${res.status})`);
+            resolvedIds.push(id);
+        }
+    }
+    if (resolvedIds.length)
+        body.repo_ids = resolvedIds;
+    return formatResponse(await client.post(`/users/${enc(username)}/tokens`, body));
 });
 registerTool('git_user_token_delete', 'Delete an access token for a user', { username: z.string().describe('Owner of the token (username in the path)'), token: z.string().describe('Token id or name to delete'), ...ConnectionParam }, async ({ username, token, connection }) => formatResponse(await clientFor(connection).delete(`/users/${enc(username)}/tokens/${token}`)));
 registerTool('git_oauth2_apps_list', 'List OAuth2 applications for the authenticated user', { ...PaginationParams, ...ConnectionParam }, async ({ page, limit, connection }) => formatResponse(await clientFor(connection).get('/user/applications/oauth2', pageQuery({ page, limit }))));
@@ -4370,6 +4439,15 @@ async function main() {
     setGeneratedServer(server);
     setRegisteredNames(registeredNames);
     registerGeneratedToolsV2();
+    // Detect the operation backends (API > mokogit-cli > git) and emit a one-time,
+    // non-fatal status line. The REST API is the primary path; mokogit-cli/git are
+    // fallbacks. Detection must never block startup, so swallow any probe error.
+    try {
+        warnBackendStatus(await probeBackends());
+    }
+    catch {
+        /* detection is best-effort; the server runs API-only regardless */
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mokoconsulting/mokogit-mcp",
-	"version": "1.13.3",
+	"version": "1.14.0",
 	"description": "MCP server for MokoGIT (Git) REST API v1 operations",
 	"type": "module",
 	"main": "dist/index.js",

package/source/config.ts

@@ -13,10 +13,11 @@
  * BRIEF: Configuration loader for MokoGIT API MCP connections
  */
 
-import { readFile, access } from 'node:fs/promises';
+import { readFile, writeFile, rename, access } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { homedir } from 'node:os';
 import type { GitConfig, GitConnection } from './types.js';
+import { resolveTokenValue, readTokenFile, migrateInlineSecret, warn } from './tokenReader.js';
 
 // Canonical config filename. Older installs may still use a pre-rename name, which
 // is read as a fallback so they keep working after the Gitea → MokoGIT rename.
@@ -60,6 +61,42 @@ async function resolveConfigPath(): Promise<string> {
 	return primary;
 }
 
+/** Extract a hostname from a baseUrl, or '' when it cannot be parsed. */
+function hostOf(baseUrl: string | undefined): string {
+	if (!baseUrl) return '';
+	try {
+		return new URL(baseUrl).host;
+	} catch {
+		return '';
+	}
+}
+
+/**
+ * Atomically rewrite the config file after a migration, preserving a leading BOM
+ * if the original had one and backing up to <config>.bak once. mode 0600.
+ * Throws on I/O failure so the caller can fall back to warn-only.
+ */
+async function rewriteConfigAtomic(configPath: string, hadBom: boolean, data: Record<string, unknown>): Promise<void> {
+	// One-time backup of the original on-disk file.
+	const bak = `${configPath}.bak`;
+	try {
+		await access(bak);
+		// .bak already exists → leave it (first-migration snapshot is the one to keep).
+	} catch {
+		try {
+			const original = await readFile(configPath, 'utf-8');
+			await writeFile(bak, original, { mode: 0o600 });
+		} catch {
+			/* best-effort; absence of a backup must not block the fix */
+		}
+	}
+
+	const body = (hadBom ? '' : '') + JSON.stringify(data, null, '\t') + '\n';
+	const tmp = `${configPath}.tmp-${process.pid}-${Date.now()}`;
+	await writeFile(tmp, body, { mode: 0o600 });
+	await rename(tmp, configPath);
+}
+
 export async function loadConfig(): Promise<GitConfig> {
 	const config_path = await resolveConfigPath();
 
@@ -67,8 +104,12 @@ export async function loadConfig(): Promise<GitConfig> {
 		const raw = await readFile(config_path, 'utf-8');
 		// #192: a config file saved with a UTF-8 BOM makes JSON.parse throw
 		// "Unexpected token" and the MCP fails to start. Strip a leading BOM first.
-		const clean = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
-		const parsed = JSON.parse(clean) as Partial<GitConfig>;
+		const hadBom = raw.charCodeAt(0) === 0xfeff;
+		const clean = hadBom ? raw.slice(1) : raw;
+		// Keep the full parsed document (not just the typed view) so a migration
+		// rewrite preserves every field we do not touch.
+		const parsedFull = JSON.parse(clean) as Record<string, unknown>;
+		const parsed = parsedFull as Partial<GitConfig> & Record<string, unknown>;
 
 		if (!parsed.connections || Object.keys(parsed.connections).length === 0) {
 			throw new Error('No connections defined in config');
@@ -77,9 +118,91 @@ export async function loadConfig(): Promise<GitConfig> {
 		// A token injected via env is the single source of truth — apply it over
 		// whatever the config file holds so a rotated token cannot leave it stale.
 		const envToken = envTokenOverride();
-		if (envToken) {
-			for (const conn of Object.values(parsed.connections)) {
-				conn.token = envToken;
+
+		// Resolve each connection's credential through the MokoCLI #1043 JSON-aware
+		// token ladder, enforcing the no-inline-secrets policy (pass 2).
+		//
+		// Precedence per connection:
+		//   1. env override (MOKOGIT_TOKEN/MOKOGITEA_TOKEN/GITEA_TOKEN) — single source
+		//      of truth. If the value is an inline literal we WARN only (there is no
+		//      config line to rewrite) and still use it.
+		//   2. conn.tokenFile — file-backed; read with §1b path-safety guards.
+		//   3. inline conn.token — WARN + AUTO-MIGRATE to ~/.ssh/tokens/<slug>.token.json,
+		//      rewrite this config to a tokenFile ref, delete the inline token, and use
+		//      the migrated file this run. On any migration error, fall back to warn-only
+		//      and keep running with the inline value (never crash, never lose the cred).
+		//
+		// A bare PAT round-trips unchanged (back-compat). A Google creds JSON is detected,
+		// warned on stderr, and left unusable (empty bearer). A needs-exchange / empty /
+		// skipped bearer is allowed to surface at use time (401), not crash at load, so one
+		// bad connection cannot take the whole server down. Secrets are never logged.
+		//
+		// mokogit-mcp sources its config only from $HOME (~/.mcp_mokogit.json) or an
+		// explicit $MOKOGIT_MCP_CONFIG / $GITEA_API_MCP_CONFIG override — both TRUSTED
+		// sources (§1b). There is NO cwd `.env` loader here, so every tokenFile reference
+		// is trusted; we pass trusted=true explicitly.
+		// Deep clone of the on-disk document that we mutate for the rewrite ONLY. The
+		// runtime objects (parsed.connections[*]) get their `.token` set to the resolved
+		// bearer for the HTTP header; the on-disk copy must instead carry a tokenFile ref
+		// and NO inline token. Keeping them separate avoids re-leaking the bearer we just
+		// assigned to the live object back into the file.
+		const rewriteDoc = JSON.parse(JSON.stringify(parsedFull)) as Record<string, unknown>;
+		const rewriteConns = rewriteDoc.connections as Record<string, Record<string, unknown>>;
+
+		let configMutated = false;
+		for (const [name, conn] of Object.entries(parsed.connections)) {
+			if (envToken) {
+				if (typeof conn.token === 'string' && conn.token.trim() && !conn.tokenFile) {
+					warn(`connection "${name}" has an inline token in the config AND an env override is set; the env token is used. The inline token is still a policy violation — move it to a tokenFile or remove it.`);
+				}
+				conn.token = resolveTokenValue(envToken, `env (${name})`).bearer;
+				continue;
+			}
+
+			if (conn.tokenFile) {
+				conn.token = (await readTokenFile(conn.tokenFile, `${name}.tokenFile`, true)).bearer;
+				continue;
+			}
+
+			// Inline literal → warn + migrate.
+			const inline = typeof conn.token === 'string' ? conn.token : '';
+			if (!inline.trim()) {
+				// Empty/missing inline token: surface the empty-credential error as before.
+				conn.token = resolveTokenValue(inline, `${name}.token`).bearer;
+				continue;
+			}
+
+			const host = hostOf(conn.baseUrl);
+			const slug = host || name;
+			try {
+				const { tokenFile, created } = await migrateInlineSecret(inline, slug, host, 'mokogit');
+				if (created) {
+					warn(`connection "${name}": inline "token" migrated to a file (no-inline-secrets policy); config rewritten to tokenFile and the inline token removed.`);
+				} else {
+					warn(`connection "${name}": inline "token" found but ${tokenFile} already exists; reusing it (not overwritten) and rewriting config to a tokenFile ref.`);
+				}
+				// Rewrite THIS connection in the on-disk clone: set tokenFile, drop inline token.
+				const connRewrite = rewriteConns[name];
+				connRewrite.tokenFile = tokenFile;
+				delete connRewrite.token;
+				conn.tokenFile = tokenFile;
+				configMutated = true;
+				// Use the migrated file this run (path-safety guards apply).
+				conn.token = (await readTokenFile(tokenFile, `${name}.tokenFile`, true)).bearer;
+			} catch (err) {
+				// Migration failed (read-only FS, perms, …): warn-only, keep running inline.
+				warn(`connection "${name}": could not migrate inline token to a file (${err instanceof Error ? err.message : String(err)}); continuing with the inline value for this run (fix manually — no-inline-secrets policy).`);
+				conn.token = resolveTokenValue(inline, `${name}.token`).bearer;
+			}
+		}
+
+		if (configMutated) {
+			try {
+				await rewriteConfigAtomic(config_path, hadBom, rewriteDoc);
+			} catch (err) {
+				// The migrated token files are written; only the config rewrite failed.
+				// Warn and keep running — the resolved bearers are already in memory.
+				warn(`migrated inline token(s) to files but could not rewrite ${config_path} (${err instanceof Error ? err.message : String(err)}); the inline token(s) remain in the config — fix the file manually.`);
 			}
 		}
 

package/source/index.ts

@@ -16,6 +16,7 @@
 
 import * as https from 'node:https';
 import * as http from 'node:http';
+import { createRequire } from 'node:module';
 import { McpServer, type ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ZodRawShapeCompat } from '@modelcontextprotocol/sdk/server/zod-compat.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -30,6 +31,7 @@ import {
 } from './generated-runtime.js';
 import { registerGeneratedToolsV2 } from './tools.generated.js';
 import { resolveGuardConfig, runGuardedMerge } from './rapid-merge-guard.js';
+import { probeBackends, warnBackendStatus, runMokoCli, cliRunEnabled, assertSafeArgs } from './mokocli.js';
 import {
 	investigatePremergeCi,
 	evaluatePremergeGate,
@@ -227,9 +229,14 @@ const OwnerRepo = {
 	repo: z.string().describe('Repository name'),
 };
 
+// Resolve the real package version from package.json (single source of truth,
+// kept in sync with the Makefile PROJECT_VERSION) rather than a hardcoded string.
+const pkg = createRequire(import.meta.url)('../package.json') as { version?: string };
+const SERVER_VERSION = pkg.version ?? '0.0.0';
+
 const server = new McpServer({
 	name: 'mokogit-mcp',
-	version: '1.5.0',
+	version: SERVER_VERSION,
 });
 
 // ── Tool registration wrapper (Git → MokoGIT brand normalization) ────
@@ -291,6 +298,56 @@ registerTool(
 	async ({ connection }) => formatResponse(await clientFor(connection).get('/user')),
 );
 
+// ── Operation backends: mokogit-cli (MokoCLI) — precedence api > mokogit-cli > git ──
+//
+// The REST API is the PRIMARY path: every other tool here calls it directly, and
+// that is what you should use for anything the API covers. The mokogit-cli binary
+// is a FALLBACK backend for CLI-only operations (or when the API is unavailable);
+// plain git is the last resort. These two tools expose that layer.
+
+registerTool(
+	'cli_status',
+	'Report the MokoGIT MCP operation backends and their precedence (api > mokogit-cli > git): which are available, the resolved mokogit-cli/git binary paths and versions, and the active backend. The REST API is always primary; mokogit-cli and git are fallbacks. Use this to check whether CLI-assisted operations are available on this host.',
+	{},
+	async () => {
+		const status = await probeBackends();
+		return { content: [{ type: 'text' as const, text: JSON.stringify(status, null, 2) }] };
+	},
+);
+
+registerTool(
+	'cli_run',
+	'Run a mokogit-cli (MokoCLI) subcommand as a FALLBACK backend and return its exit code, stdout and stderr. DISABLED by default — an operator must opt in with $MOKOGIT_ENABLE_CLI_RUN=1 (arbitrary CLI execution). Precedence is api > mokogit-cli > git — prefer the REST API tools for anything they cover; use this only for CLI-only operations or when the API is unavailable. Arguments are passed as argv (no shell); option-like args (leading "-") are rejected unless allowlisted or $MOKOGIT_CLI_ALLOW_FLAGS=1; any cwd must be inside $MOKOGIT_CLI_WORKDIR. Refuses with a clear message when disabled or when mokogit-cli is not installed (check cli_status).',
+	{
+		args: z.array(z.string()).describe('mokogit-cli arguments as an argv array, e.g. ["version"] or ["repo","list"]. Passed directly to the binary (no shell).'),
+		cwd: z.string().optional().describe('Working directory — must resolve inside $MOKOGIT_CLI_WORKDIR (optional).'),
+		timeout_seconds: z.number().int().positive().max(600).optional().describe('Max run time in seconds (default 60).'),
+		input: z.string().optional().describe('Optional data to write to the CLI’s stdin.'),
+	},
+	async ({ args, cwd, timeout_seconds, input }) => {
+		if (!cliRunEnabled()) {
+			return { content: [{ type: 'text' as const, text: 'cli_run is disabled. Arbitrary mokogit-cli execution is an operator opt-in — set $MOKOGIT_ENABLE_CLI_RUN=1 to enable it. The REST API tools are the primary path (precedence api > mokogit-cli > git); use cli_status to see backend availability.' }] };
+		}
+		try {
+			assertSafeArgs(args);
+			const r = await runMokoCli(args, {
+				cwd,
+				timeoutMs: timeout_seconds ? timeout_seconds * 1000 : undefined,
+				input,
+			});
+			const text = [
+				`$ ${r.command}`,
+				`exit: ${r.code}${r.ok ? '' : ' (non-zero)'}`,
+				r.stdout ? `\n--- stdout ---\n${r.stdout.trimEnd()}` : '',
+				r.stderr ? `\n--- stderr ---\n${r.stderr.trimEnd()}` : '',
+			].filter(Boolean).join('\n');
+			return { content: [{ type: 'text' as const, text }] };
+		} catch (err) {
+			return { content: [{ type: 'text' as const, text: err instanceof Error ? err.message : String(err) }] };
+		}
+	},
+);
+
 registerTool(
 	'git_user_orgs',
 	'List organizations the authenticated user belongs to',
@@ -2042,7 +2099,7 @@ registerTool(
 		const results: string[] = [];
 
 		// 1. Try to create the GitHub repo via GitHub API
-		const ghRes = await fetch(`https://api.github.com/orgs/${ghOrg}/repos`, {
+		const ghRes = await fetch(`https://api.github.com/orgs/${enc(ghOrg)}/repos`, {
 			method: 'POST',
 			headers: {
 				'Authorization': `Bearer ${ghToken}`,
@@ -2114,7 +2171,7 @@ registerTool(
 		const results: string[] = [];
 
 		// 1. Create GitHub repo (if needed)
-		const ghRes = await fetch(`https://api.github.com/orgs/${ghOrg}/repos`, {
+		const ghRes = await fetch(`https://api.github.com/orgs/${enc(ghOrg)}/repos`, {
 			method: 'POST',
 			headers: {
 				'Authorization': `Bearer ${ghToken}`,
@@ -2141,7 +2198,7 @@ registerTool(
 		}
 
 		// 2. Enable wiki on GitHub repo (in case it was disabled)
-		await fetch(`https://api.github.com/repos/${ghOrg}/${repo}`, {
+		await fetch(`https://api.github.com/repos/${enc(ghOrg)}/${enc(repo)}`, {
 			method: 'PATCH',
 			headers: {
 				'Authorization': `Bearer ${ghToken}`,
@@ -2269,7 +2326,7 @@ registerTool(
 		task: z.string().describe('Cron task name (e.g. "repo_health_check", "resync_all_hooks", "repo_archive_cleanup")'),
 		...ConnectionParam,
 	},
-	async ({ task, connection }) => formatResponse(await clientFor(connection).post(`/admin/cron/${task}`, {})),
+	async ({ task, connection }) => formatResponse(await clientFor(connection).post(`/admin/cron/${enc(task)}`, {})),
 );
 
 // ── Generic API Call ────────────────────────────────────────────────────
@@ -4053,12 +4110,33 @@ registerTool(
 		username: z.string().describe('Owner of the token (username in the path)'),
 		name: z.string().describe('Name of the token'),
 		scopes: z.array(z.string()).optional().describe('Token scopes (e.g. ["read:user", "write:repository"])'),
+		all_repos: z.boolean().optional().describe('Token covers all repos incl. future (default true)'),
+		repo_ids: z.array(z.number()).optional().describe('When all_repos=false, restrict to these repository IDs'),
+		repos: z.array(z.string()).optional().describe('Convenience: repo full-names (owner/name) resolved to IDs client-side'),
 		...ConnectionParam,
 	},
-	async ({ username, name, scopes, connection }) => {
+	async ({ username, name, scopes, all_repos, repo_ids, repos, connection }) => {
+		const client = clientFor(connection);
 		const body: Record<string, unknown> = { name };
 		if (scopes) body.scopes = scopes;
-		return formatResponse(await clientFor(connection).post(`/users/${enc(username)}/tokens`, body));
+		if (all_repos !== undefined) body.all_repos = all_repos;
+		// Resolve any repo full-names (owner/name) to numeric IDs and merge with
+		// any explicit repo_ids. The forge expects the field name `repo_ids`.
+		const resolvedIds: number[] = Array.isArray(repo_ids) ? [...repo_ids] : [];
+		if (repos?.length) {
+			for (const full of repos) {
+				const slash = full.indexOf('/');
+				if (slash < 0) throw new Error(`repos entries must be "owner/name": got "${full}"`);
+				const ownerPart = full.slice(0, slash);
+				const repoPart = full.slice(slash + 1);
+				const res = await client.get(`/repos/${enc(ownerPart)}/${enc(repoPart)}`);
+				const id = (res.data as { id?: number } | null)?.id;
+				if (typeof id !== 'number') throw new Error(`Could not resolve repository id for "${full}" (status ${res.status})`);
+				resolvedIds.push(id);
+			}
+		}
+		if (resolvedIds.length) body.repo_ids = resolvedIds;
+		return formatResponse(await client.post(`/users/${enc(username)}/tokens`, body));
 	},
 );
 
@@ -7151,6 +7229,14 @@ async function main(): Promise<void> {
 	setGeneratedServer(server);
 	setRegisteredNames(registeredNames);
 	registerGeneratedToolsV2();
+	// Detect the operation backends (API > mokogit-cli > git) and emit a one-time,
+	// non-fatal status line. The REST API is the primary path; mokogit-cli/git are
+	// fallbacks. Detection must never block startup, so swallow any probe error.
+	try {
+		warnBackendStatus(await probeBackends());
+	} catch {
+		/* detection is best-effort; the server runs API-only regardless */
+	}
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
 }

package/source/mokocli.ts

@@ -0,0 +1,328 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: mokogit-mcp.MokoCli
+ * INGROUP: mokogit-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokogit-mcp
+ * PATH: /source/mokocli.ts
+ * VERSION: 01.00.00
+ * BRIEF: Operation-backend detection + invocation for the MokoGIT MCP.
+ *        Resolves the mokogit-cli (MokoCLI) binary and plain git at runtime and
+ *        exposes them as FALLBACK backends behind the REST API. Fleet precedence
+ *        is API > mokogit-cli > git: the REST API is always the primary path, the
+ *        CLI is the first fallback, git the last. Detection is non-fatal — when a
+ *        binary is absent the MCP warns once on stderr and keeps running API-only.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { statSync, realpathSync } from 'node:fs';
+import { delimiter, join, isAbsolute, resolve, sep } from 'node:path';
+
+const execFileP = promisify(execFile);
+const IS_WIN = process.platform === 'win32';
+
+/**
+ * Resolve a binary name/path to an ABSOLUTE path by searching $PATH explicitly
+ * (like `which`/`where`), honoring PATHEXT on Windows. Returns null when not
+ * found. Running the resolved absolute path — never a bare name — prevents
+ * cwd-relative / planted-binary resolution (Windows CreateProcess search order).
+ */
+function resolveExecutable(nameOrPath: string): string | null {
+	const isFile = (p: string): boolean => {
+		try { return statSync(p).isFile(); } catch { return false; }
+	};
+	// Explicit path (absolute or contains a separator): accept only if it is a file.
+	// On Windows, refuse a .bat/.cmd target (BatBadBut — argv is not safely escaped
+	// when execFile spawns cmd.exe for a batch file), even when set via $MOKOGIT_CLI.
+	if (isAbsolute(nameOrPath) || nameOrPath.includes('/') || (IS_WIN && nameOrPath.includes('\\'))) {
+		if (IS_WIN && /\.(bat|cmd)$/i.test(nameOrPath)) return null;
+		const abs = resolve(nameOrPath);
+		return isFile(abs) ? abs : null;
+	}
+	// Bare name: search PATH directories in order. NEVER include '.' / cwd.
+	// On Windows accept ONLY .EXE/.COM — never .BAT/.CMD. Running a batch file via
+	// execFile spawns cmd.exe and argv is not safely escaped (BatBadBut / CVE-2024-27980),
+	// so a batch target would reintroduce command injection through args. Honor
+	// PATHEXT order but intersect it with the exe/com allowlist.
+	const WIN_SAFE_EXTS = ['.COM', '.EXE'];
+	const exts = IS_WIN
+		? (() => {
+			const fromEnv = (process.env.PATHEXT ?? '').split(';').map((e) => e.trim().toUpperCase()).filter((e) => WIN_SAFE_EXTS.includes(e));
+			return fromEnv.length ? fromEnv : WIN_SAFE_EXTS;
+		})()
+		: [''];
+	const dirs = (process.env.PATH ?? '').split(delimiter).filter((d) => d && d.trim() && d !== '.');
+	for (const dir of dirs) {
+		for (const ext of exts) {
+			const cand = join(dir, nameOrPath + (IS_WIN ? ext : ''));
+			if (isFile(cand)) return resolve(cand);
+		}
+	}
+	return null;
+}
+
+/** Operation backends, in fleet precedence order (highest first). */
+export const BACKEND_PRECEDENCE = ['api', 'mokogit-cli', 'git'] as const;
+export type Backend = (typeof BACKEND_PRECEDENCE)[number];
+
+/** Candidate binary names searched on PATH for the MokoCLI, in order. */
+const MOKOCLI_CANDIDATES = ['mokogit-cli', 'mokogit', 'mokocli'];
+/** Env vars that may hold an explicit MokoCLI path (checked before PATH). */
+const MOKOCLI_ENV_VARS = ['MOKOGIT_CLI', 'MOKOCLI', 'MOKOGIT_CLI_PATH'];
+
+const VERSION_TIMEOUT_MS = 5000;
+
+export interface BinaryProbe {
+	available: boolean;
+	/** Resolved command (an absolute path from an env var, or a PATH-resolved name). */
+	path: string | null;
+	/** First line of `--version` output, when it could be read. */
+	version: string | null;
+	/** How it was resolved: an env var name, 'path', or null when not found. */
+	source: string | null;
+}
+
+export interface BackendStatus {
+	/** Static precedence order (API > mokogit-cli > git). */
+	precedence: Backend[];
+	/** The REST API is always the primary path; reachability is per-request. */
+	api: { available: true; note: string };
+	mokogitCli: BinaryProbe & { envVarsChecked: string[]; candidates: string[] };
+	git: BinaryProbe;
+	/** Available backends in precedence order (api is always present). */
+	availableChain: Backend[];
+	/** Highest-precedence backend usable for a generic op — always 'api'. */
+	active: Backend;
+}
+
+/** Run `<bin> <versionArgs>` and return its trimmed first output line, or null. */
+async function readVersion(bin: string, versionArgs: string[]): Promise<string | null> {
+	try {
+		const { stdout, stderr } = await execFileP(bin, versionArgs, {
+			timeout: VERSION_TIMEOUT_MS,
+			windowsHide: true,
+		});
+		const out = (stdout || stderr || '').trim();
+		return out ? out.split(/\r?\n/, 1)[0].trim() : '';
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Probe for a binary: try each env var (as an explicit command/path) first, then
+ * each PATH candidate, accepting the first whose `--version` runs successfully.
+ */
+async function probeBinary(
+	envVars: string[],
+	candidates: string[],
+	versionArgs: string[] = ['--version'],
+): Promise<BinaryProbe> {
+	for (const ev of envVars) {
+		const val = process.env[ev];
+		if (val && val.trim()) {
+			const abs = resolveExecutable(val.trim());
+			if (abs) {
+				const ver = await readVersion(abs, versionArgs);
+				if (ver !== null) return { available: true, path: abs, version: ver || null, source: ev };
+			}
+		}
+	}
+	for (const name of candidates) {
+		const abs = resolveExecutable(name);
+		if (abs) {
+			const ver = await readVersion(abs, versionArgs);
+			if (ver !== null) return { available: true, path: abs, version: ver || null, source: 'path' };
+		}
+	}
+	return { available: false, path: null, version: null, source: null };
+}
+
+/**
+ * Build a MINIMAL environment for the child process: only the variables the CLI
+ * needs to locate itself, find its home/temp, and authenticate — never the full
+ * parent environment. Prevents leaking unrelated secrets into the subprocess.
+ */
+function minimalChildEnv(): NodeJS.ProcessEnv {
+	const allow = [
+		'PATH', 'Path', 'PATHEXT', 'SystemRoot', 'windir', 'ComSpec',
+		'TEMP', 'TMP', 'TMPDIR', 'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH',
+		'LANG', 'LC_ALL', 'LC_CTYPE',
+		// MokoGIT auth / CLI config the CLI may need to operate
+		'MOKOGIT_TOKEN', 'MOKOGITEA_TOKEN', 'GITEA_TOKEN',
+		'MOKOGIT_CLI', 'MOKOCLI', 'MOKOGIT_CLI_PATH',
+		'MOKOGIT_MCP_CONFIG', 'GITEA_API_MCP_CONFIG',
+		'MOKOGIT_HOST', 'MOKOGIT_URL',
+	];
+	const env: NodeJS.ProcessEnv = {};
+	for (const k of allow) if (process.env[k] !== undefined) env[k] = process.env[k];
+	return env;
+}
+
+/**
+ * Validate a caller-supplied cwd. Running the CLI in an arbitrary directory is a
+ * risk (relative config/hook pickup), so a cwd is honored ONLY when it resolves
+ * inside the operator-configured workspace root $MOKOGIT_CLI_WORKDIR. Returns the
+ * resolved cwd to use, or throws. When no cwd is requested, the configured root
+ * (if any) is used; otherwise the child inherits the MCP's own cwd.
+ */
+function resolveCwd(requested?: string): string | undefined {
+	const rootRaw = process.env.MOKOGIT_CLI_WORKDIR;
+	const root = rootRaw && rootRaw.trim() ? realpathSync(resolve(rootRaw.trim())) : null;
+	if (!requested) return root ?? undefined;
+	if (!root) {
+		throw new Error('A cwd was requested but no workspace root is configured. Set $MOKOGIT_CLI_WORKDIR to an allowed directory to use cwd.');
+	}
+	let abs: string;
+	try { abs = realpathSync(resolve(root, requested)); } catch { throw new Error(`cwd does not exist or is not accessible: ${requested}`); }
+	if (abs !== root && !abs.startsWith(root + sep)) {
+		throw new Error(`cwd must be inside the configured workspace root ($MOKOGIT_CLI_WORKDIR): ${root}`);
+	}
+	return abs;
+}
+
+let cached: Promise<BackendStatus> | null = null;
+
+/** Detect the available operation backends. Cached after the first call. */
+export function probeBackends(force = false): Promise<BackendStatus> {
+	if (cached && !force) return cached;
+	cached = (async (): Promise<BackendStatus> => {
+		const [cli, git] = await Promise.all([
+			probeBinary(MOKOCLI_ENV_VARS, MOKOCLI_CANDIDATES),
+			probeBinary([], ['git']),
+		]);
+		const availableChain: Backend[] = ['api'];
+		if (cli.available) availableChain.push('mokogit-cli');
+		if (git.available) availableChain.push('git');
+		return {
+			precedence: [...BACKEND_PRECEDENCE],
+			api: { available: true, note: 'primary path — all MCP tools call the MokoGIT REST API directly' },
+			mokogitCli: { ...cli, envVarsChecked: MOKOCLI_ENV_VARS, candidates: MOKOCLI_CANDIDATES },
+			git,
+			availableChain,
+			active: 'api',
+		};
+	})();
+	return cached;
+}
+
+let warned = false;
+
+/**
+ * Emit a one-time, non-fatal status line to stderr describing backend
+ * availability. Absence of the CLI is informational, not an error — the REST API
+ * is the primary path and the server runs fine without the CLI.
+ */
+export function warnBackendStatus(status: BackendStatus): void {
+	if (warned) return;
+	warned = true;
+	if (status.mokogitCli.available) {
+		process.stderr.write(
+			`mokogit-cli detected (${status.mokogitCli.path}${status.mokogitCli.version ? ` — ${status.mokogitCli.version}` : ''}); ` +
+			`available as a fallback backend. Precedence: api > mokogit-cli > git.\n`,
+		);
+	} else {
+		process.stderr.write(
+			`mokogit-cli not found (checked ${MOKOCLI_ENV_VARS.join('/')} and PATH: ${MOKOCLI_CANDIDATES.join(', ')}). ` +
+			`CLI-assisted fallback is disabled — operating API-only (precedence api > mokogit-cli > git). ` +
+			`Install mokogit-cli or set $MOKOGIT_CLI to enable it.\n`,
+		);
+	}
+}
+
+export interface CliRunResult {
+	ok: boolean;
+	code: number | null;
+	stdout: string;
+	stderr: string;
+	command: string;
+}
+
+const RUN_TIMEOUT_MS = 60000;
+const MAX_BUFFER = 8 * 1024 * 1024;
+
+const TRUTHY = /^(1|true|on|yes)$/i;
+
+/**
+ * Whether the cli_run passthrough is enabled. Arbitrary CLI execution is an
+ * explicit operator opt-in and is DISABLED by default — set
+ * $MOKOGIT_ENABLE_CLI_RUN=1 to allow it.
+ */
+export function cliRunEnabled(): boolean {
+	return TRUTHY.test((process.env.MOKOGIT_ENABLE_CLI_RUN ?? '').trim());
+}
+
+/** Global flags permitted even though they start with '-'. */
+const ALLOWED_FLAGS = new Set(['-h', '--help', '-v', '--version', '--json']);
+
+/**
+ * Reject option-like args (leading '-') not in the allowlist, so a default-on
+ * cli_run cannot be handed arbitrary flags. Operators who need full flags set
+ * $MOKOGIT_CLI_ALLOW_FLAGS=1. Throws with a clear message on a rejected arg.
+ */
+export function assertSafeArgs(args: string[]): void {
+	if (TRUTHY.test((process.env.MOKOGIT_CLI_ALLOW_FLAGS ?? '').trim())) return;
+	for (const a of args) {
+		if (a.startsWith('-') && !ALLOWED_FLAGS.has(a)) {
+			throw new Error(
+				`Refused: option-like argument "${a}" is not allowed by default. ` +
+				`Allowed flags: ${[...ALLOWED_FLAGS].join(', ')}. Set $MOKOGIT_CLI_ALLOW_FLAGS=1 to permit arbitrary flags.`,
+			);
+		}
+	}
+}
+
+/**
+ * Invoke the resolved mokogit-cli with argv (NOT a shell string — no shell
+ * interpolation). Throws if the CLI is unavailable; resolves with the exit code,
+ * stdout and stderr otherwise (a non-zero exit is returned, not thrown).
+ */
+export async function runMokoCli(
+	args: string[],
+	opts: { cwd?: string; timeoutMs?: number; input?: string } = {},
+): Promise<CliRunResult> {
+	const status = await probeBackends();
+	if (!status.mokogitCli.available || !status.mokogitCli.path) {
+		throw new Error(
+			'mokogit-cli is not available on this host (checked ' +
+			`${MOKOCLI_ENV_VARS.join('/')} and PATH: ${MOKOCLI_CANDIDATES.join(', ')}). ` +
+			'Use the REST API tools (primary path), or install mokogit-cli / set $MOKOGIT_CLI.',
+		);
+	}
+	// status.mokogitCli.path is an ABSOLUTE path resolved at probe time via an
+	// explicit PATH search — we never exec a bare name (no cwd-relative/planted
+	// binary). cwd is allowlisted to $MOKOGIT_CLI_WORKDIR; the child gets a minimal
+	// environment and no shell (execFile passes argv directly).
+	const bin = status.mokogitCli.path;
+	const cwd = resolveCwd(opts.cwd);
+	const command = `${bin} ${args.join(' ')}`;
+	try {
+		const child = execFileP(bin, args, {
+			cwd,
+			timeout: opts.timeoutMs ?? RUN_TIMEOUT_MS,
+			maxBuffer: MAX_BUFFER,
+			windowsHide: true,
+			shell: false,
+			env: minimalChildEnv(),
+		});
+		if (opts.input !== undefined && child.child.stdin) {
+			child.child.stdin.end(opts.input);
+		}
+		const { stdout, stderr } = await child;
+		return { ok: true, code: 0, stdout: stdout ?? '', stderr: stderr ?? '', command };
+	} catch (err) {
+		const e = err as { code?: number; stdout?: string; stderr?: string; message?: string };
+		return {
+			ok: false,
+			code: typeof e.code === 'number' ? e.code : null,
+			stdout: e.stdout ?? '',
+			stderr: e.stderr ?? e.message ?? String(err),
+			command,
+		};
+	}
+}

package/source/tokenReader.ts

@@ -0,0 +1,231 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * MokoCLI #1043 — JSON-aware credential/token reader (vendored per-repo).
+ * GitHub standard primary; Google secondary = DETECT + WARN (no exchange).
+ * Secret values are NEVER written to stdout and NEVER echoed in errors/warnings.
+ *
+ * Detection ladder (resolveTokenValue):
+ *   1. trim; empty -> throw (no silent anonymous request).
+ *   2. JSON.parse; parse-fail OR non-object(array/null/scalar) -> the trimmed
+ *      string IS the bearer (bare PAT, `gh auth token` output).  [raw]
+ *   3. object .type in {service_account, authorized_user, external_account,
+ *      impersonated_service_account}  OR  (.refresh_token && .token_uri)
+ *      -> GOOGLE: emit a stderr WARNING and return an UNUSABLE result
+ *         (bearer '', needsExchange true). Never bearer a private key.
+ *   4. else .token || .access_token -> bearer (+ expiry/scope/permissions). [github-json]
+ *   5. else -> throw (unrecognized object; never leak the blob as a token).
+ */
+import { readFile, writeFile, rename, mkdir, stat, access, chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve, sep } from 'node:path';
+
+export type TokenKind = 'raw' | 'github-json' | 'google';
+
+export interface ResolvedToken {
+	/** Bearer value to send. '' when unusable (Google needs-exchange). */
+	bearer: string;
+	kind: TokenKind;
+	/** true for Google creds — not usable as a bearer by this server. */
+	needsExchange?: boolean;
+	expiresAt?: string;
+	expiresIn?: number;
+	scopes?: string[];
+	permissions?: Record<string, unknown>;
+}
+
+const GOOGLE_TYPES = new Set([
+	'service_account',
+	'authorized_user',
+	'external_account',
+	'impersonated_service_account',
+]);
+
+/** Expand a leading "~" to $HOME, then resolve to an absolute path. */
+export function expandHome(p: string): string {
+	if (p === '~') return homedir();
+	if (p.startsWith('~/') || p.startsWith('~\\')) return resolve(homedir(), p.slice(2));
+	return resolve(p);
+}
+
+/** stderr ONLY — must never touch stdout (the MCP stdio channel). Never prints secret values. */
+export function warn(msg: string): void {
+	process.stderr.write(`[token] WARNING: ${msg}\n`);
+}
+
+/** Largest credential file we will open (§1b path-safety cap). */
+const MAX_TOKEN_FILE_BYTES = 64 * 1024;
+
+/** Reduce an arbitrary label to the safe slug charset [A-Za-z0-9._-]. */
+export function sanitizeSlug(s: string): string {
+	return (s || '').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'connection';
+}
+
+/** True when `abs` is $HOME itself or lives beneath it (no `..` escape). */
+function isWithinHome(abs: string): boolean {
+	const home = resolve(homedir());
+	return abs === home || abs.startsWith(home + sep);
+}
+
+/**
+ * Resolve RAW credential content into a bearer per MokoCLI #1043.
+ * `source` only labels errors/warnings; secret values are never echoed.
+ */
+export function resolveTokenValue(raw: string, source = 'credential'): ResolvedToken {
+	const trimmed = (raw ?? '').trim();
+	if (!trimmed) {
+		throw new Error(`Credential "${source}" is empty — refusing an anonymous request (set the token or remove the connection).`);
+	}
+
+	let obj: unknown;
+	try {
+		obj = JSON.parse(trimmed);
+	} catch {
+		return { bearer: trimmed, kind: 'raw' }; // bare PAT / `gh auth token`
+	}
+	if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+		return { bearer: trimmed, kind: 'raw' };
+	}
+
+	const o = obj as Record<string, unknown>;
+	const type = typeof o.type === 'string' ? o.type : '';
+	const isGoogle = GOOGLE_TYPES.has(type) || (typeof o.refresh_token === 'string' && typeof o.token_uri === 'string');
+	if (isGoogle) {
+		warn(`credential "${source}" is a Google ${type || 'OAuth token-cache'} JSON; this server does not perform Google token exchange, so it will NOT be used (a private key is never sent as a bearer token).`);
+		return { bearer: '', kind: 'google', needsExchange: true };
+	}
+
+	const bearer = typeof o.token === 'string' ? o.token : typeof o.access_token === 'string' ? o.access_token : '';
+	if (bearer) {
+		const scopes = Array.isArray(o.scopes)
+			? o.scopes.map(String)
+			: typeof o.scope === 'string'
+				? o.scope.split(/\s+/).filter(Boolean)
+				: undefined;
+		const expiresAt = typeof o.expires_at === 'string' ? o.expires_at : typeof o.expiry === 'string' ? o.expiry : undefined;
+		const expiresIn = typeof o.expires_in === 'number' ? o.expires_in : undefined;
+		const permissions = o.permissions && typeof o.permissions === 'object' ? (o.permissions as Record<string, unknown>) : undefined;
+		return { bearer, kind: 'github-json', expiresAt, expiresIn, scopes, permissions };
+	}
+
+	throw new Error(`Credential "${source}" is an unrecognized JSON object (no "token"/"access_token") — refusing to use it as a bearer token.`);
+}
+
+/**
+ * Read a token file (~ expands) and resolve it per #1043, with §1b PATH SAFETY.
+ *
+ * A credential-file reference can otherwise be abused to read an arbitrary local
+ * file (e.g. a path pointing at /etc/shadow or ~/.ssh/id_rsa) and exfiltrate it as
+ * a bearer to an attacker-controlled target. Only honor a reference from a TRUSTED
+ * config source (the process environment or the user's HOME config / explicit
+ * $..._CONFIG). mokogit-mcp has NO cwd `.env` loader, so every tokenFile reference
+ * here already comes from a trusted source; `trusted` defaults to true and is passed
+ * explicitly from config.ts for clarity / future-proofing.
+ *
+ * Path constraints enforced before the file is opened: regular file, located under
+ * $HOME (no absolute-outside-home, no `..` escape), owner-read/write only
+ * (mode & 0o077 === 0), size ≤ 64 KiB. On any failure: stderr WARN naming the path
+ * + reason and SKIP (return an unusable result) — never read/send its contents,
+ * never crash. Files we auto-write (migrateInlineSecret) are 0600 under
+ * ~/.ssh/tokens, so they always pass.
+ */
+export async function readTokenFile(path: string, source?: string, trusted = true): Promise<ResolvedToken> {
+	const abs = expandHome(path);
+	const label = source ?? abs;
+
+	if (!trusted) {
+		warn(`refusing credential-file reference "${abs}" from an untrusted source (${label}); a file path is only honored from env or the HOME config — SKIPPING.`);
+		return { bearer: '', kind: 'raw', needsExchange: true };
+	}
+
+	if (!isWithinHome(abs)) {
+		warn(`credential file "${abs}" (${label}) is outside $HOME — refusing to read it (path-safety) — SKIPPING.`);
+		return { bearer: '', kind: 'raw', needsExchange: true };
+	}
+
+	let st: Awaited<ReturnType<typeof stat>>;
+	try {
+		st = await stat(abs);
+	} catch (err) {
+		warn(`credential file "${abs}" (${label}) could not be stat'd: ${err instanceof Error ? err.message : String(err)} — SKIPPING.`);
+		return { bearer: '', kind: 'raw', needsExchange: true };
+	}
+	if (!st.isFile()) {
+		warn(`credential file "${abs}" (${label}) is not a regular file — SKIPPING.`);
+		return { bearer: '', kind: 'raw', needsExchange: true };
+	}
+	// Owner-only perms: no group/world read/write/execute bits. Windows / MSYS do
+	// not model POSIX perms (stat.mode returns synthetic 0666/0444 regardless of the
+	// real ACL), so the check is POSIX-only; on win32 it is skipped and the file is
+	// trusted on the strength of the within-$HOME + regular-file + size guards.
+	if (process.platform !== 'win32' && (st.mode & 0o077) !== 0) {
+		warn(`credential file "${abs}" (${label}) is group/world-accessible (mode ${(st.mode & 0o777).toString(8)}); run \`chmod 600 "${abs}"\` — SKIPPING.`);
+		return { bearer: '', kind: 'raw', needsExchange: true };
+	}
+	if (st.size > MAX_TOKEN_FILE_BYTES) {
+		warn(`credential file "${abs}" (${label}) is ${st.size} bytes (> ${MAX_TOKEN_FILE_BYTES} cap) — SKIPPING.`);
+		return { bearer: '', kind: 'raw', needsExchange: true };
+	}
+
+	let raw: string;
+	try {
+		raw = await readFile(abs, 'utf-8');
+	} catch (err) {
+		warn(`failed to read credential file "${abs}" (${label}): ${err instanceof Error ? err.message : String(err)} — SKIPPING.`);
+		return { bearer: '', kind: 'raw', needsExchange: true };
+	}
+	return resolveTokenValue(raw, label);
+}
+
+export interface MigrationResult {
+	/** Absolute path of the token file now holding the secret. */
+	tokenFile: string;
+	/** true when this call created the file; false when an existing file was reused. */
+	created: boolean;
+}
+
+/**
+ * §1 AUTO-MIGRATE an inline secret to ~/.ssh/tokens/<slug>.token.json (self-heal).
+ *
+ * Writes { token, host, note, migrated_at } at mode 0600 (never overwriting an
+ * existing file), and returns the path so the caller can rewrite the config to a
+ * tokenFile reference and drop the inline value. The secret is NEVER logged. The
+ * caller is responsible for the config rewrite + .bak; this function only owns the
+ * token-file side. Throws on I/O failure so the caller can fall back to warn-only.
+ */
+export async function migrateInlineSecret(secret: string, slug: string, host: string, serverName: string): Promise<MigrationResult> {
+	const tokensDir = resolve(homedir(), '.ssh', 'tokens');
+	await mkdir(tokensDir, { recursive: true, mode: 0o700 });
+
+	const target = resolve(tokensDir, `${sanitizeSlug(slug)}.token.json`);
+
+	// Do not clobber an existing token file — reuse it instead.
+	try {
+		await access(target);
+		return { tokenFile: target, created: false };
+	} catch {
+		// does not exist → write it
+	}
+
+	const payload = JSON.stringify(
+		{
+			token: secret,
+			host: host || undefined,
+			note: `auto-migrated from inline ${serverName} MCP config (no-inline-secrets policy, MokoCLI #1043)`,
+			migrated_at: new Date().toISOString(),
+		},
+		null,
+		'\t',
+	);
+
+	// Atomic-ish: write a sibling temp 0600, then rename into place.
+	const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
+	await writeFile(tmp, payload + '\n', { mode: 0o600 });
+	try {
+		await chmod(tmp, 0o600);
+	} catch {
+		/* best-effort on platforms without POSIX perms */
+	}
+	await rename(tmp, target);
+	return { tokenFile: target, created: true };
+}

package/source/types.ts

@@ -16,6 +16,12 @@
 export interface GitConnection {
 	baseUrl: string;
 	token: string;
+	/**
+	 * Optional path to a file holding the token/credential (MokoCLI #1043).
+	 * Read via readTokenFile and resolved through the JSON-aware token ladder;
+	 * "~" expands to $HOME. Takes effect only when no env override is present.
+	 */
+	tokenFile?: string;
 	/** Skip TLS certificate verification (self-signed certs) */
 	insecure?: boolean;
 }