@mokoconsulting/mokoabs-mcp 1.1.0 → 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: 01.01.00
+	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: 01.01.00
+	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    := mcp-mokoabs
-PROJECT_VERSION := 01.01.00
+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: 01.01.00
+VERSION: 04.01.00
 BRIEF: Security vulnerability reporting and handling policy
 -->
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mokoconsulting/mokoabs-mcp",
-	"version": "1.1.0",
+	"version": "4.1.0",
 	"description": "MCP server for Audiobookshelf API operations",
 	"type": "module",
 	"main": "dist/index.js",
@@ -16,7 +16,7 @@
 		"clean": "rm -rf dist/"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.12.1",
+		"@modelcontextprotocol/sdk": "1.12.1",
 		"zod": "^3.24.4"
 	},
 	"devDependencies": {

package/sample/config.example.json

@@ -1,9 +1,15 @@
 {
+	"_comment": "No inline secrets. Lead every connection with the file-backed `tokenFile`. An inline `apiKey` is deprecated/legacy and is auto-migrated to ~/.ssh/tokens/<slug>.token.json (and this config rewritten) on first run.",
 	"defaultConnection": "production",
 	"connections": {
 		"production": {
 			"baseUrl": "https://abs.mokoconsulting.tech",
-			"apiKey": "your-audiobookshelf-api-key"
+			"tokenFile": "~/.ssh/tokens/abs.mokoconsulting.tech.token"
+		},
+		"legacy-inline": {
+			"_comment": "DEPRECATED: inline apiKey. Shown only to illustrate the legacy shape; it is auto-migrated to a token file on first run.",
+			"baseUrl": "https://abs.example.com",
+			"apiKey": "legacy-inline-api-key-auto-migrated-on-first-run"
 		}
 	}
 }

package/source/client.ts

@@ -32,12 +32,15 @@ export class ApiClient {
 		this.base_url = conn.baseUrl.replace(/\/+$/, '') + API_PREFIX;
 
 		// ── Customize auth headers ──────────────────────────────────
+		// The bearer is resolved at config-load time (MokoCLI #1043) from the
+		// connection's apiKey/tokenFile; fall back to a raw apiKey for safety.
 		// Examples:
-		//   Bearer token:  { 'Authorization': `Bearer ${conn.apiKey}` }
-		//   API key header: { 'DOLAPIKEY': conn.apiKey }
+		//   Bearer token:  { 'Authorization': `Bearer ${conn.bearer}` }
+		//   API key header: { 'DOLAPIKEY': conn.bearer }
 		//   Basic auth:    { 'Authorization': `Basic ${btoa(user + ':' + pass)}` }
+		const bearer = conn.bearer ?? conn.apiKey ?? '';
 		this.headers = {
-			'Authorization': `Bearer ${conn.apiKey}`,
+			'Authorization': `Bearer ${bearer}`,
 			'Content-Type': 'application/json',
 			'Accept': 'application/json',
 		};

package/source/config.ts

@@ -17,6 +17,8 @@ import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { homedir } from 'node:os';
 import type { ApiConfig, ApiConnection } from './types.js';
+import { resolveTokenValue, readTokenFile } from './tokenReader.js';
+import { migrateInlineSecret, safeCredentialPath } from './credentialStore.js';
 
 // ── Customize this ──────────────────────────────────────────────────────
 // Change the filename to match your project (e.g. ".dolibarr-api-mcp.json")
@@ -38,6 +40,16 @@ export async function loadConfig(): Promise<ApiConfig> {
 			throw new Error('No connections defined in config');
 		}
 
+		// Resolve each connection's credential into a bearer per MokoCLI #1043.
+		// A file-backed `tokenFile` takes precedence over an inline `apiKey`.
+		// Raw bearer strings pass through unchanged (back-compat); GitHub JSON
+		// blobs yield their token/access_token; Google creds are refused. Any
+		// inline `apiKey` literal is warned + auto-migrated to a token file and
+		// the on-disk config is rewritten (no-inline-secrets policy, Pass 2).
+		for (const [name, conn] of Object.entries(parsed.connections)) {
+			await resolveConnectionBearer(conn, name, config_path);
+		}
+
 		return {
 			connections: parsed.connections,
 			defaultConnection: parsed.defaultConnection ?? Object.keys(parsed.connections)[0],
@@ -51,6 +63,70 @@ export async function loadConfig(): Promise<ApiConfig> {
 	}
 }
 
+/**
+ * Resolve a single connection's credential into `conn.bearer` (in place).
+ *
+ * Precedence: a file-backed `tokenFile` wins over an inline `apiKey`. The chosen
+ * credential runs through the MokoCLI #1043 ladder — raw strings pass through,
+ * GitHub JSON yields its token/access_token, Google creds are detected and
+ * refused (unusable bearer). Secret values are never logged.
+ *
+ * No-inline-secrets (Pass 2): a `tokenFile` from the HOME config is a TRUSTED
+ * source and is path-safety-checked (§1b) before being read. An inline `apiKey`
+ * literal is warned + auto-migrated to ~/.ssh/tokens/<slug>.token.json and the
+ * on-disk config rewritten; the current run still uses the resolved bearer even
+ * if migration falls back to warn-only.
+ */
+async function resolveConnectionBearer(conn: ApiConnection, name: string, configPath: string): Promise<void> {
+	let resolved;
+
+	if (conn.tokenFile) {
+		// §1b path safety — the config is a trusted source (HOME / $MOKOABS_CONFIG).
+		const safe = safeCredentialPath(conn.tokenFile, { trusted: true });
+		if (!safe) {
+			throw new Error(`Connection "${name}" tokenFile "${conn.tokenFile}" failed credential-file safety checks (see warning above).`);
+		}
+		resolved = await readTokenFile(safe, `connection "${name}".tokenFile`);
+	} else if (conn.apiKey !== undefined) {
+		// Resolve first (validates shape; raw passes through). Then, if the value
+		// is an inline literal secret, auto-migrate it out of the config.
+		resolved = resolveTokenValue(conn.apiKey, `connection "${name}".apiKey`);
+
+		const migrated = migrateInlineSecret({
+			configPath,
+			connectionName: name,
+			field: 'apiKey',
+			secret: conn.apiKey,
+			baseUrl: conn.baseUrl,
+			primary: true,
+		});
+		if (migrated) {
+			// Reflect the migration in the in-memory config for this run, and use
+			// the FILE as the authoritative secret going forward (§1.6). When an
+			// existing token file was reused, its contents may differ from the
+			// inline value we just resolved — re-resolve from the file so the
+			// current run matches what every future run will use.
+			conn.tokenFile = migrated.tokenFile;
+			delete conn.apiKey;
+			const safe = safeCredentialPath(migrated.tokenFile, { trusted: true });
+			if (safe) {
+				resolved = await readTokenFile(safe, `connection "${name}".tokenFile (migrated)`);
+			}
+		}
+	} else {
+		throw new Error(`Connection "${name}" has neither "apiKey" nor "tokenFile" — nothing to authenticate with.`);
+	}
+
+	if (resolved.needsExchange || !resolved.bearer) {
+		throw new Error(
+			`Connection "${name}" credential is not usable as a bearer token` +
+			(resolved.kind === 'google' ? ' (Google credentials require token exchange, which this server does not perform).' : '.'),
+		);
+	}
+
+	conn.bearer = resolved.bearer;
+}
+
 export function getConnection(config: ApiConfig, name?: string): ApiConnection {
 	const key = name ?? config.defaultConnection;
 	const conn = config.connections[key];

package/source/credentialStore.ts

@@ -0,0 +1,216 @@
+/* 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: mokoabs-mcp.CredentialStore
+ * INGROUP: mokoabs-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoabs-mcp
+ * PATH: /source/credentialStore.ts
+ * VERSION: 01.00.00
+ * BRIEF: No-inline-secrets policy — auto-migration + credential-file path safety.
+ *
+ * Policy (MokoCLI #1043, Pass 2): no secure information may EVER be inline in the
+ * MCP settings file. For mokoabs-mcp the only secret field is a connection's
+ * `apiKey` (the Audiobookshelf bearer). When an inline literal is found in the
+ * on-disk config we warn + auto-migrate it to ~/.ssh/tokens/<slug>.token.json and
+ * rewrite the config to reference it via `tokenFile`. Secret values are NEVER
+ * printed; warnings go to stderr only (stdout is the MCP stdio channel).
+ */
+import { constants as FS } from 'node:fs';
+import {
+	accessSync,
+	chmodSync,
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	statSync,
+	writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { expandHome } from './tokenReader.js';
+
+/** stderr ONLY — never stdout; never prints secret values. */
+function warn(msg: string): void {
+	process.stderr.write(`[credential] WARNING: ${msg}\n`);
+}
+
+/** Max size for a credential file we are willing to read (64 KiB). */
+const MAX_CRED_FILE_BYTES = 64 * 1024;
+
+/** Sanitize an arbitrary label into a safe filename fragment ([A-Za-z0-9._-]). */
+function sanitizeSlug(s: string): string {
+	return (s || '').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'connection';
+}
+
+/** Derive the host portion of a baseUrl, or '' if unparseable. */
+function hostOf(baseUrl: string | undefined): string {
+	if (!baseUrl) return '';
+	try {
+		return new URL(baseUrl).host;
+	} catch {
+		return '';
+	}
+}
+
+/**
+ * Validate a credential-file reference before it is read (section 1b).
+ * Returns the resolved absolute path when safe, or null (after a stderr warning)
+ * when it must be skipped. `trusted` MUST be false for any reference that came
+ * from an untrusted source (e.g. a cwd .env) — those are never honored as paths.
+ */
+export function safeCredentialPath(ref: string, opts: { trusted: boolean }): string | null {
+	if (!opts.trusted) {
+		warn(`credential-file reference "${ref}" came from an untrusted source (cwd .env) — refusing to open it; provide the secret inline or via the HOME config.`);
+		return null;
+	}
+	const abs = expandHome(ref);
+	const home = resolve(homedir());
+	const rel = relative(home, abs);
+	// Must resolve to a path strictly under $HOME (reject the home dir itself,
+	// any absolute path outside home, and any ".." escape).
+	if (rel === '' || rel.startsWith('..') || rel.split(/[\\/]/).includes('..')) {
+		warn(`credential file "${abs}" is outside $HOME (or escapes it via "..") — refusing to open it.`);
+		return null;
+	}
+	let st;
+	try {
+		st = statSync(abs);
+	} catch (err) {
+		warn(`credential file "${abs}" could not be stat'd (${err instanceof Error ? err.message : String(err)}) — skipping.`);
+		return null;
+	}
+	if (!st.isFile()) {
+		warn(`credential file "${abs}" is not a regular file — skipping.`);
+		return null;
+	}
+	// Owner-read-only: no group/world bits. (On Windows these bits are not
+	// meaningfully enforced, so skip the perm check there to avoid false rejects.)
+	if (process.platform !== 'win32' && (st.mode & 0o077) !== 0) {
+		warn(`credential file "${abs}" is group/world accessible (mode ${(st.mode & 0o777).toString(8)}) — refusing to open it; chmod 600.`);
+		return null;
+	}
+	if (st.size > MAX_CRED_FILE_BYTES) {
+		warn(`credential file "${abs}" is larger than ${MAX_CRED_FILE_BYTES} bytes — refusing to open it (not a credential file).`);
+		return null;
+	}
+	return abs;
+}
+
+export interface MigrationResult {
+	/** Absolute path of the file now holding the secret (may be a pre-existing one). */
+	tokenFile: string;
+}
+
+/**
+ * Auto-migrate an inline secret out of the on-disk config into
+ * ~/.ssh/tokens/<slug>.token.json and rewrite the config to reference it.
+ * Returns the token-file path on success, or null (warn-only) if migration
+ * could not be completed — the caller then keeps using the inline value.
+ *
+ * NEVER throws for an expected failure (read-only FS, perms): warns and returns
+ * null so the server keeps running with the inline value.
+ */
+export function migrateInlineSecret(args: {
+	configPath: string;
+	connectionName: string;
+	field: string;
+	secret: string;
+	baseUrl?: string;
+	/** Whether `field` is the primary bearer field (no suffix) or a secondary one. */
+	primary: boolean;
+}): MigrationResult | null {
+	const { configPath, connectionName, field, secret, baseUrl, primary } = args;
+	try {
+		// Only migrate the real on-disk config (it must exist and be writable).
+		if (!existsSync(configPath)) return null;
+		try {
+			accessSync(configPath, FS.W_OK);
+		} catch {
+			warn(`inline secret ${connectionName}.${field} detected but config "${configPath}" is not writable — keeping inline (warn-only).`);
+			return null;
+		}
+
+		const tokensDir = join(resolve(homedir()), '.ssh', 'tokens');
+		mkdirSync(tokensDir, { recursive: true, mode: 0o700 });
+
+		const base = sanitizeSlug(hostOf(baseUrl) || connectionName);
+		const suffix = primary ? '' : `-${sanitizeSlug(field)}`;
+		const target = join(tokensDir, `${base}${suffix}.token.json`);
+
+		let reusedExisting = false;
+		if (existsSync(target)) {
+			reusedExisting = true;
+		} else {
+			const payload = JSON.stringify(
+				{
+					token: secret,
+					host: hostOf(baseUrl) || undefined,
+					note: 'auto-migrated from inline mokoabs MCP config (no-inline-secrets policy, MokoCLI #1043)',
+					migrated_at: new Date().toISOString(),
+				},
+				null,
+				2,
+			);
+			writeFileSync(target, payload + '\n', { mode: 0o600, flag: 'wx' });
+		}
+
+		// Back up the config ONCE (preserving the old inline secret), then rewrite.
+		const backup = `${configPath}.bak`;
+		if (!existsSync(backup)) {
+			try {
+				copyFileSync(configPath, backup, FS.COPYFILE_EXCL);
+			} catch {
+				// Non-fatal: continue with the rewrite even if the backup races.
+			}
+			try {
+				// Harden the backup perms; it still holds the old secret.
+				chmodSync(backup, 0o600);
+			} catch { /* best-effort */ }
+		}
+
+		rewriteConfigTokenFile(configPath, connectionName, field, target);
+
+		if (reusedExisting) {
+			warn(`inline secret ${connectionName}.${field} migrated: a token file already existed at ${target}; reusing it (did NOT overwrite). Config rewritten to reference it. Backup at ${backup} STILL CONTAINS the old inline secret — delete it after verifying.`);
+		} else {
+			warn(`inline secret ${connectionName}.${field} migrated to ${target} (mode 0600) and config rewritten to reference it via tokenFile. Backup at ${backup} STILL CONTAINS the old inline secret — delete ${backup} after verifying the migration.`);
+		}
+		return { tokenFile: target };
+	} catch (err) {
+		warn(`auto-migration of ${connectionName}.${field} failed (${err instanceof Error ? err.message : String(err)}) — keeping inline value (warn-only).`);
+		return null;
+	}
+}
+
+/**
+ * Atomically rewrite the config: set connection[field→tokenFile] = target and
+ * delete the inline `field`. Preserves all other fields; writes temp + rename.
+ */
+function rewriteConfigTokenFile(configPath: string, connectionName: string, field: string, target: string): void {
+	const raw = readFileSync(configPath, 'utf-8');
+	const parsed = JSON.parse(raw) as {
+		connections?: Record<string, Record<string, unknown>>;
+		[k: string]: unknown;
+	};
+	const conn = parsed.connections?.[connectionName];
+	if (!conn) throw new Error(`connection "${connectionName}" vanished from config`);
+
+	// Map the inline secret field to its file-ref field. For mokoabs the only
+	// secret is apiKey → tokenFile; a generic *_password would map to *File.
+	const fileField = field === 'apiKey' ? 'tokenFile' : `${field}File`;
+	conn[fileField] = `~/${relative(resolve(homedir()), target).split(/[\\/]/).join('/')}`;
+	delete conn[field];
+
+	const tmp = `${configPath}.tmp-${process.pid}-${Date.now()}`;
+	writeFileSync(tmp, JSON.stringify(parsed, null, '\t') + '\n', { mode: 0o600 });
+	renameSync(tmp, configPath);
+	try {
+		chmodSync(configPath, 0o600);
+	} catch { /* best-effort on platforms without POSIX perms */ }
+}

package/source/tokenReader.ts

@@ -0,0 +1,120 @@
+/* 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: mokoabs-mcp.TokenReader
+ * INGROUP: mokoabs-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoabs-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.
+ *
+ * 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);
+}

package/source/types.ts

@@ -25,8 +25,23 @@
 export interface ApiConnection {
 	/** Base URL of the API instance (no trailing slash) */
 	baseUrl: string;
-	/** API key or token for authentication */
-	apiKey: string;
+	/**
+	 * API key or token for authentication. Either a raw bearer string (passes
+	 * through unchanged) or a JSON credential blob (GitHub token/access_token,
+	 * or a Google credential which is detected and refused) per MokoCLI #1043.
+	 * Optional when `tokenFile` is supplied instead.
+	 */
+	apiKey?: string;
+	/**
+	 * Path to a file holding the credential (~ expands). Read and resolved per
+	 * MokoCLI #1043; takes precedence over inline `apiKey` when both are set.
+	 */
+	tokenFile?: string;
+	/**
+	 * Resolved bearer value used for `Authorization: Bearer <bearer>`. Populated
+	 * by loadConfig() from `apiKey`/`tokenFile`; not provided by users directly.
+	 */
+	bearer?: string;
 	/** Skip TLS certificate verification (self-signed certs) */
 	insecure?: boolean;
 }