@mokoconsulting/mokologs-mcp 4.0.3 → 4.1.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/CODE_OF_CONDUCT.md

@@ -14,7 +14,7 @@
 	DEFGROUP: 
 	INGROUP: Project.Documentation
 	REPO: MokoConsulting/Template-NPM
-	VERSION: 00.00.01
+	VERSION: 04.01.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/Template-NPM
-	VERSION: 00.00.01
+	VERSION: 04.01.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    := mokologs-mcp
-PROJECT_VERSION := 04.00.03
+PROJECT_VERSION := 04.01.00
 PLATFORM        := npm
 
 # ==============================================================================

package/SECURITY.md

@@ -23,7 +23,7 @@ DEFGROUP: Template-Generic
 INGROUP: Template-Generic.Documentation
 REPO: https://git.mokoconsulting.tech/MokoConsulting/Template-Generic
 PATH: /SECURITY.md
-VERSION: 04.00.15
+VERSION: 04.01.00
 BRIEF: Security vulnerability reporting and handling policy
 -->
 

package/config.example.json

@@ -1,9 +1,15 @@
 {
+	"//": "No-inline-secrets policy (MokoCLI #1043): token fields MUST be file refs, e.g. \"file:~/.ssh/tokens/<name>.token\". An inline literal token is auto-migrated to ~/.ssh/tokens/<slug>.token.json on first run and this file is rewritten to a file: ref (a one-time .bak is kept — delete it after verifying). SSH keys/passphrases/passwords and the mysql password are NOT affected by this policy.",
 	"defaultSource": "local",
 	"maxBytes": 262144,
 	"maxLines": 2000,
 	"redaction": { "secrets": true, "email": true, "creditcard": true, "jwt": true, "ip": false },
-	"notify": { "ntfyUrl": "https://ntfy.sh", "topic": "mokologs-alerts", "token": "file:~/.ssh/tokens/ntfy.token" },
+	"notify": {
+		"ntfyUrl": "https://ntfy.sh",
+		"topic": "mokologs-alerts",
+		"token": "file:~/.ssh/tokens/ntfy.token",
+		"//token-legacy": "DEPRECATED: an inline \"token\": \"<literal>\" is auto-migrated to a file on first run. Prefer the file: ref above."
+	},
 	"sources": {
 		"local": {
 			"type": "local",
@@ -36,7 +42,8 @@
 			"type": "gitea",
 			"label": "MokoGIT CI logs",
 			"baseUrl": "https://git.mokoconsulting.tech",
-			"token": "file:~/.ssh/tokens/git.mokoconsulting.tech.jmiller.token"
+			"token": "file:~/.ssh/tokens/git.mokoconsulting.tech.jmiller.token",
+			"//token-legacy": "DEPRECATED: an inline \"token\": \"<literal>\" is auto-migrated to a file on first run. Prefer the file: ref above."
 		}
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mokoconsulting/mokologs-mcp",
-	"version": "4.0.3",
+	"version": "4.1.0",
 	"description": "MCP server for multi-source log triage & analysis — discover, tail, search, and assess logs across local and remote sources",
 	"type": "module",
 	"main": "dist/index.js",
@@ -14,7 +14,7 @@
 		"clean": "rm -rf dist/"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.12.1",
+		"@modelcontextprotocol/sdk": "1.12.1",
 		"ssh2": "^1.16.0",
 		"zod": "^3.24.4"
 	},

package/source/config.ts

@@ -19,6 +19,8 @@ import { resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { z } from 'zod';
 import type { LogsConfig, LogSource } from './types.js';
+import { resolveTokenValue } from './tokenReader.js';
+import { isFileRef, migrateInlineToken, safeReadCredentialFile, hostOf, type MigrationPlan } from './tokenMigrate.js';
 
 const CONFIG_FILENAME = '.mokologs-mcp.json';
 const CONFIG_ENV_VAR = 'MOKOLOGS_CONFIG';
@@ -114,10 +116,63 @@ export function resolveSecret(value: string | undefined): string | undefined {
 	return readFileSync(p, 'utf-8').trim();
 }
 
-/** Resolve all `file:`-backed secrets on a source (returns a copy). */
-function resolveSourceSecrets(src: LogSource): LogSource {
+/** Context needed to warn + auto-migrate an inline token during a load. */
+interface MigrateCtx {
+	/** Mutable parsed config object (rewritten in place + on disk on migration). */
+	rawObj: Record<string, unknown>;
+	/** On-disk config path to rewrite. */
+	configPath: string;
+	/** Shared one-time `.bak` flag. */
+	backup: { done: boolean };
+}
+
+/**
+ * Resolve a TOKEN field only, enforcing the no-inline-secrets policy:
+ *   - `file:` ref  → PATH-GUARDED read (§1b: within-$HOME, regular file,
+ *                    owner-only perms, ≤64 KiB) then the #1043 JSON ladder.
+ *   - inline value → WARN + AUTO-MIGRATE to ~/.ssh/tokens/<slug>.token.json
+ *                    (0600), rewrite the config to a `file:` ref, then read it
+ *                    back via the guarded path. Migration failure → warn-only,
+ *                    use the inline value directly for this run.
+ *
+ * ONLY for token fields (notify.token, source.token) — NEVER for SSH
+ * keys/passphrases/passwords or the mysql password (those stay raw).
+ *
+ * @param plan  JSON-path + slug/host metadata for a possible migration.
+ */
+function resolveTokenSecret(value: string | undefined, label: string, ctx: MigrateCtx, plan: Omit<MigrationPlan, 'value' | 'label'>): string | undefined {
+	if (value === undefined) return undefined;
+
+	// Already file-backed: guarded read + #1043 ladder. No migration, no warning.
+	if (isFileRef(value)) {
+		const raw = safeReadCredentialFile(value, label);
+		if (raw === undefined) return undefined; // path-safety skip already warned
+		return resolveTokenValue(raw, label).bearer || undefined;
+	}
+
+	// Inline literal → warn + auto-migrate, then read back the migrated file.
+	const fileRef = migrateInlineToken(ctx.rawObj, ctx.configPath, { ...plan, value, label }, ctx.backup);
+	if (fileRef !== undefined) {
+		const raw = safeReadCredentialFile(fileRef, label);
+		if (raw !== undefined) return resolveTokenValue(raw, label).bearer || undefined;
+		// migrated file somehow unreadable — fall through to the inline value
+	}
+	// Migration failed (or migrated file unreadable): use the inline value this run.
+	return resolveTokenValue(value, label).bearer || undefined;
+}
+
+/** Resolve all `file:`-backed secrets on a source (returns a copy). The token
+ *  field gets the policy treatment; SSH key/passphrase/password and the mysql
+ *  password stay RAW via resolveSecret (unchanged). */
+function resolveSourceSecrets(name: string, src: LogSource, ctx: MigrateCtx): LogSource {
 	const out: LogSource = { ...src };
-	if (out.token) out.token = resolveSecret(out.token);
+	if (out.token) {
+		out.token = resolveTokenSecret(out.token, `source "${name}".token`, ctx, {
+			path: ['sources', name, 'token'],
+			slugBasis: hostOf(src.baseUrl) ?? name,
+			host: hostOf(src.baseUrl),
+		});
+	}
 	if (out.ssh) {
 		out.ssh = {
 			...out.ssh,
@@ -138,21 +193,29 @@ export async function loadConfig(): Promise<LogsConfig> {
 		: resolve(homedir(), CONFIG_FILENAME);
 
 	let parsed: z.infer<typeof ConfigSchema>;
+	let rawObj: Record<string, unknown>;
 	try {
 		const raw = await readFile(configPath, 'utf-8');
-		parsed = ConfigSchema.parse(JSON.parse(raw));
+		rawObj = JSON.parse(raw) as Record<string, unknown>;
+		parsed = ConfigSchema.parse(rawObj);
 	} catch (err) {
 		const message =
 			err instanceof z.ZodError ? err.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ') : err instanceof Error ? err.message : String(err);
 		throw new Error(`Failed to load config from ${configPath}: ${message}\nCreate ${configPath} — see config.example.json for format.`);
 	}
 
+	// Shared migration context: inline TOKEN fields self-heal into ~/.ssh/tokens
+	// and the on-disk config is rewritten to file: refs (atomic, one 0600 .bak).
+	const ctx: MigrateCtx = { rawObj, configPath, backup: { done: false } };
+
 	const sources: Record<string, LogSource> = {};
 	for (const [name, src] of Object.entries(parsed.sources)) {
-		sources[name] = resolveSourceSecrets(src as LogSource);
+		sources[name] = resolveSourceSecrets(name, src as LogSource, ctx);
 	}
 
-	const notify = parsed.notify ? { ...parsed.notify, token: resolveSecret(parsed.notify.token) } : undefined;
+	const notify = parsed.notify
+		? { ...parsed.notify, token: resolveTokenSecret(parsed.notify.token, 'notify.token', ctx, { path: ['notify', 'token'], slugBasis: hostOf(parsed.notify.ntfyUrl) ?? 'ntfy', host: hostOf(parsed.notify.ntfyUrl) }) }
+		: undefined;
 
 	return {
 		sources,

package/source/tokenMigrate.ts

@@ -0,0 +1,258 @@
+/* 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: mokologs-mcp.TokenMigrate
+ * INGROUP: mokologs-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokologs-mcp
+ * PATH: /source/tokenMigrate.ts
+ * VERSION: 01.00.00
+ * BRIEF: No-inline-secrets self-heal for TOKEN fields + credential-file path safety.
+ *
+ * SCOPE (mokologs-mcp): applies ONLY to the two TOKEN fields `notify.token` and
+ * `sources.<name>.token`. SSH private keys / passphrases / passwords and the
+ * mysql password are NOT migrated — they stay inline/raw exactly as before
+ * (they are legitimately PEM/opaque and out of scope for the JSON token policy).
+ *
+ * Behaviour (MokoCLI #1043 no-inline-secrets policy):
+ *   - A `file:<path>` token ref is left untouched; its read is PATH-GUARDED (§1b).
+ *   - An inline literal token in ~/.mokologs-mcp.json is WARNED + AUTO-MIGRATED
+ *     to ~/.ssh/tokens/<slug>.token.json (0600), the config rewritten to a
+ *     `file:` ref (atomic, with a one-time 0600 .bak), and the value used for
+ *     this run. Any migration error → warn-only (never crash, never lose creds).
+ *   - Secret values are NEVER written to stdout and NEVER echoed in warnings.
+ */
+import {
+	chmodSync,
+	closeSync,
+	constants as fsConstants,
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	renameSync,
+	statSync,
+	writeFileSync,
+	writeSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve, sep } from 'node:path';
+
+const TOKENS_DIR = () => resolve(homedir(), '.ssh', 'tokens');
+const MAX_CRED_BYTES = 64 * 1024; // §1b size cap
+
+/** stderr ONLY — never stdout (the MCP stdio channel). Never prints secret values. */
+function warn(msg: string): void {
+	process.stderr.write(`[token] WARNING: ${msg}\n`);
+}
+
+/** Expand a leading `~` and the `file:` prefix to an absolute path. */
+export function fileRefToPath(ref: string): string {
+	let p = ref.startsWith('file:') ? ref.slice('file:'.length) : ref;
+	if (p.startsWith('~')) p = resolve(homedir(), p.slice(1).replace(/^[/\\]/, ''));
+	return resolve(p);
+}
+
+/** True when a token value is a `file:` reference (already file-backed). */
+export function isFileRef(value: string | undefined): boolean {
+	return typeof value === 'string' && value.startsWith('file:');
+}
+
+/**
+ * §1b credential-file PATH SAFETY. A `file:` token ref from a trusted source
+ * (HOME config) may still point anywhere; guard every read:
+ *   - resolve under $HOME (reject absolute-outside-home and any `..` escape),
+ *   - regular file,
+ *   - owner-only perms (mode & 0o077 === 0),
+ *   - size ≤ 64 KiB.
+ * On any failure: stderr WARN (naming path + reason) and return undefined (SKIP) —
+ * never read/return the contents, never crash.
+ */
+export function safeReadCredentialFile(ref: string, label: string): string | undefined {
+	const abs = fileRefToPath(ref);
+	const home = resolve(homedir());
+
+	// within-$HOME + no-`..` escape (compare resolved absolute path against $HOME)
+	const rel = abs.slice(home.length);
+	const underHome = abs === home || (abs.startsWith(home + sep) && !rel.split(sep).includes('..'));
+	if (!underHome) {
+		warn(`credential file for ${label} ("${abs}") is outside $HOME or escapes it via "..": refusing to read it.`);
+		return undefined;
+	}
+
+	let st;
+	try {
+		st = statSync(abs);
+	} catch (err) {
+		warn(`credential file for ${label} ("${abs}") could not be stat'd (${err instanceof Error ? err.message : String(err)}): skipping.`);
+		return undefined;
+	}
+	if (!st.isFile()) {
+		warn(`credential file for ${label} ("${abs}") is not a regular file: skipping.`);
+		return undefined;
+	}
+	// owner-only perms. (Windows reports mode 0o666 and lacks POSIX bits — skip the
+	// perms gate there; the within-HOME + regular-file + size checks still apply.)
+	if (process.platform !== 'win32' && (st.mode & 0o077) !== 0) {
+		warn(`credential file for ${label} ("${abs}") is group/world accessible (mode ${(st.mode & 0o777).toString(8)}); expected owner-only (chmod 600): skipping.`);
+		return undefined;
+	}
+	if (st.size > MAX_CRED_BYTES) {
+		warn(`credential file for ${label} ("${abs}") is ${st.size} bytes (> ${MAX_CRED_BYTES} cap): skipping.`);
+		return undefined;
+	}
+	try {
+		return readFileSync(abs, 'utf-8');
+	} catch (err) {
+		warn(`credential file for ${label} ("${abs}") could not be read (${err instanceof Error ? err.message : String(err)}): skipping.`);
+		return undefined;
+	}
+}
+
+/** Sanitize an identifier for use in a token filename (`[A-Za-z0-9._-]`). */
+function slugify(s: string): string {
+	return (s || 'token').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'token';
+}
+
+/** Derive the host for the token metadata/slug from a baseUrl (if any). */
+function hostOf(baseUrl: string | undefined): string | undefined {
+	if (!baseUrl) return undefined;
+	try {
+		return new URL(baseUrl).host || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export interface MigrationPlan {
+	/** JSON path segments to the inline token field, e.g. ['notify','token']. */
+	path: string[];
+	/** The inline secret value (never logged). */
+	value: string;
+	/** Label for warnings, e.g. `source "mokogit-ci".token`. */
+	label: string;
+	/** Preferred slug basis (host from baseUrl, else connection/field name). */
+	slugBasis: string;
+	/** Host to record in the token JSON metadata, when known. */
+	host?: string;
+}
+
+/** Write a file with an explicit mode, failing if it already exists (COPYFILE_EXCL semantics). */
+function writeNewFile0600(path: string, contents: string): void {
+	const fd = openSync(path, 'wx', 0o600); // wx = O_CREAT|O_EXCL → throws if exists
+	try {
+		writeSync(fd, contents);
+	} finally {
+		closeSync(fd);
+	}
+	try {
+		chmodSync(path, 0o600);
+	} catch {
+		/* best effort on platforms without chmod */
+	}
+}
+
+/**
+ * Perform one inline-token migration: write the token file, rewrite the config
+ * atomically to a `file:` ref, and return the `file:` ref to use for this run.
+ * On ANY error, warn-only and return undefined (caller keeps the inline value).
+ *
+ * @param rawConfigObj  the mutable parsed config object (rewritten in place + on disk)
+ * @param configPath    the on-disk config file to rewrite
+ * @param plan          which field to migrate
+ * @param backupState   shared flag so the `.bak` is created at most once per load
+ */
+export function migrateInlineToken(
+	rawConfigObj: Record<string, unknown>,
+	configPath: string,
+	plan: MigrationPlan,
+	backupState: { done: boolean },
+): string | undefined {
+	try {
+		const dir = TOKENS_DIR();
+		mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+		const host = plan.host;
+		const slug = slugify(host ?? plan.slugBasis);
+		const target = resolve(dir, `${slug}.token.json`);
+		const fileRef = `file:${target}`;
+
+		if (existsSync(target)) {
+			warn(`inline secret ${plan.label} not migrated: token file "${target}" already exists; reusing it (verify it holds the right token). Remove the inline value from "${configPath}".`);
+			// Still rewrite the config to point at the existing file + drop the inline value.
+		} else {
+			const tokenJson =
+				JSON.stringify(
+					{
+						token: plan.value,
+						host: host ?? '',
+						note: 'auto-migrated from inline mokologs MCP config (no-inline-secrets policy, MokoCLI #1043)',
+						migrated_at: new Date().toISOString(),
+					},
+					null,
+					'\t',
+				) + '\n';
+			writeNewFile0600(target, tokenJson);
+			warn(
+				`inline secret ${plan.label} migrated → "${target}" (mode 0600); config "${configPath}" rewritten to a file: reference. ` +
+					`A one-time backup "${configPath}.bak" STILL CONTAINS the old inline secret — delete it after verifying the migration.`,
+			);
+		}
+
+		// Rewrite the config: set the field to the file: ref, then persist atomically.
+		setByPath(rawConfigObj, plan.path, fileRef);
+		backupAndWriteConfig(rawConfigObj, configPath, backupState);
+		return fileRef;
+	} catch (err) {
+		warn(`could not auto-migrate inline secret ${plan.label} (${err instanceof Error ? err.message : String(err)}): keeping the inline value for this run (no config change).`);
+		return undefined;
+	}
+}
+
+/** Set obj[path[0]][path[1]]... = value (assumes the parents exist). */
+function setByPath(obj: Record<string, unknown>, path: string[], value: unknown): void {
+	let cur: Record<string, unknown> = obj;
+	for (let i = 0; i < path.length - 1; i++) {
+		cur = cur[path[i]] as Record<string, unknown>;
+	}
+	cur[path[path.length - 1]] = value;
+}
+
+/**
+ * Back the config up ONCE (0600, only if no `.bak` yet) then write the mutated
+ * object atomically (temp file + rename), mode 0600.
+ */
+function backupAndWriteConfig(obj: Record<string, unknown>, configPath: string, backupState: { done: boolean }): void {
+	const bak = `${configPath}.bak`;
+	if (!backupState.done && !existsSync(bak)) {
+		// copy then chmod (COPYFILE_EXCL guards against a race)
+		copyFileSync(configPath, bak, fsConstants.COPYFILE_EXCL);
+		try {
+			chmodSync(bak, 0o600);
+		} catch {
+			/* best effort */
+		}
+	}
+	backupState.done = true;
+
+	const tmp = `${configPath}.tmp-${process.pid}-${Date.now()}`;
+	const contents = JSON.stringify(obj, null, '\t') + '\n';
+	writeFileSync(tmp, contents, { mode: 0o600 });
+	try {
+		chmodSync(tmp, 0o600);
+	} catch {
+		/* best effort */
+	}
+	renameSync(tmp, configPath); // atomic replace on the same filesystem
+	try {
+		chmodSync(configPath, 0o600);
+	} catch {
+		/* best effort */
+	}
+}
+
+export { hostOf };

package/source/tokenReader.ts

@@ -0,0 +1,125 @@
+/* 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: mokologs-mcp.TokenReader
+ * INGROUP: mokologs-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokologs-mcp
+ * PATH: /source/tokenReader.ts
+ * VERSION: 01.00.00
+ * BRIEF: 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.
+ *
+ * SCOPE (mokologs-mcp): apply ONLY to the token fields (notify.token,
+ * source.token). SSH private keys / passphrases / passwords and the mysql
+ * password are legitimately raw PEM/opaque strings and must NOT be routed
+ * through this ladder — they keep returning RAW via resolveSecret.
+ *
+ * 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 } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } 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. */
+function warn(msg: string): void {
+	process.stderr.write(`[token] WARNING: ${msg}\n`);
+}
+
+/**
+ * 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. */
+export async function readTokenFile(path: string, source?: string): Promise<ResolvedToken> {
+	const abs = expandHome(path);
+	let raw: string;
+	try {
+		raw = await readFile(abs, 'utf-8');
+	} catch (err) {
+		throw new Error(`Failed to read token file "${abs}": ${err instanceof Error ? err.message : String(err)}`);
+	}
+	return resolveTokenValue(raw, source ?? abs);
+}