`mintlify dev` fails with "Client not built" on macOS arm64 — npm tar@6.1.15 silently skips .next/ directory during extraction

[TurekBot]

(I'd love to file this bug in the correct place, but I don't seem to have access to github.com/mintlify/mint)

Environment

OS	macOS 15.5 Sequoia (Build 24F74)
CPU	arm64 (Apple Silicon)
Node	v22.15.1
mintlify CLI	4.2.543
tar package	6.1.15 (pinned by @mintlify/previewing)

What happened

Running mintlify dev from the repo root fails immediately after the "preparing local preview…" spinner with:

Error: Client not built. Run: cd <path>/apps/client && STANDALONE_BUILD=true NEXT_PUBLIC_ENV=cli yarn build
    at setupNext (file:///~/.n/lib/node_modules/mintlify/node_modules/@mintlify/previewing/dist/local-preview/setupNext.js:37:19)
    at run (file:///~/.n/lib/node_modules/mintlify/node_modules/@mintlify/previewing/dist/local-preview/run.js:51:34)
    at dev (file:///~/.n/lib/node_modules/mintlify/node_modules/@mintlify/previewing/dist/local-preview/index.js:58:11)

Running mintlify update (before or after the failure) reports "already up to date", so there is no indication the cache is broken.

Root cause

@mintlify/previewing downloads the client tarball to ~/.mintlify/mint.tar.gz and extracts it using the npm tar package (tar.x({ sync: true, ... })). The tarball does contain mint/apps/client/.next/ — confirmed by inspecting it directly:

tar -tzf /tmp/mint-0.0.2862.tar.gz | grep "apps/client/.next" | head -5
# mint/apps/client/.next/
# mint/apps/client/.next/required-server-files.json
# mint/apps/client/.next/BUILD_ID
# ...

However, after @mintlify/previewing extracts the same tarball, ~/.mintlify/mint/apps/client/.next/ is absent. When the system tar binary extracts the identical file, .next/ is present and mintlify dev starts successfully. The npm tar@6.1.15 package appears to silently drop the dotfile directory on this platform.

Without apps/client/.next/required-server-files.json, setupNext() throws the "Client not built" error.

Steps to reproduce

1. Install mintlify globally: npm i -g mintlify
2. Clone any Mintlify docs repo
3. cd into the repo and run mintlify dev
4. Observe the "Client not built" error after the spinner

Most likely to hit on a fresh install or after clearing ~/.mintlify.

Workaround

# 1. Clear the broken cache
rm -rf ~/.mintlify

# 2. Download and extract with system tar (handles dotfile directories correctly)
VERSION=$(curl -s https://releases.mintlify.com/mint-version.txt)
mkdir -p ~/.mintlify
curl -s -o /tmp/mint.tar.gz "https://releases.mintlify.com/mint-${VERSION}.tar.gz"
tar -xzf /tmp/mint.tar.gz -C ~/.mintlify
echo "$VERSION" > ~/.mintlify/mint/mint-version.txt
rm /tmp/mint.tar.gz

# 3. Run normally — the version file prevents a re-download
mintlify dev

Suggested fix

Either upgrade tar to a version that reliably extracts dotfile directories on macOS arm64, or add a post-extraction check that verifies apps/client/.next/required-server-files.json exists and surfaces a clear error (with the workaround steps) if it doesn't, rather than failing later in setupNext().