Skip to content

Turn any document into clean, AI-ready Markdown. Local-first desktop app: reads scanned PDFs, batches folders, runs offline, and uses far fewer tokens than vision models.

fix: v0.3.1 - pin uv 0.12.3, resolve resources next to the executable, send MDFlux User-Agent

ibrahimqureshae9e830069f6b7
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b292ab3..871c447 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -78,6 +78,7 @@ jobs:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
with:
+ version: "0.12.3"
enable-cache: true
cache-dependency-glob: |
app/src-tauri/resources/sidecar/requirements.lock
@@ -112,6 +113,7 @@ jobs:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
with:
+ version: "0.12.3"
enable-cache: true
cache-dependency-glob: |
app/src-tauri/resources/sidecar/requirements.lock
@@ -144,3 +146,4 @@ jobs:
run: |
python tools/dependencies/check.py
python tools/release/check_workflow_tools.py
+ python -m unittest tests.test_check_workflow_tools tests.test_check_packaged_app
diff --git a/.github/workflows/release-candidate.yml b/.github/workflows/release-candidate.yml
index 6428e54..d15f87f 100644
--- a/.github/workflows/release-candidate.yml
+++ b/.github/workflows/release-candidate.yml
@@ -92,7 +92,7 @@ jobs:
- name: Install Tauri Linux build prerequisites
run: |
sudo apt-get update
- sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev javascriptcoregtk-4.1-dev patchelf pkg-config build-essential
+ sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev javascriptcoregtk-4.1-dev patchelf pkg-config build-essential xvfb
- uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c
- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6
with:
@@ -113,6 +113,7 @@ jobs:
ref: ${{ needs.validate-ref.outputs.commit }}
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
with:
+ version: "0.12.3"
enable-cache: true
cache-dependency-glob: |
app/src-tauri/resources/sidecar/requirements.lock
@@ -144,6 +145,7 @@ jobs:
ref: ${{ needs.validate-ref.outputs.commit }}
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
with:
+ version: "0.12.3"
enable-cache: true
cache-dependency-glob: |
app/src-tauri/resources/sidecar/requirements.lock
@@ -192,6 +194,8 @@ jobs:
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
with: { python-version: "3.12" }
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
+ with:
+ version: "0.12.3"
- id: version
shell: pwsh
run: |
@@ -208,7 +212,7 @@ jobs:
uv venv --python 3.12 .venv-verifier
$verifierPython = (Resolve-Path .venv-verifier/Scripts/python.exe).Path
uv pip install --python $verifierPython --require-hashes -r app/src-tauri/resources/sidecar/requirements-full.lock
- $output = & $verifierPython -m tools.release --archive "$archive" --platform windows-x64 --edition lite --json-out dist/verification-windows-x64-lite.json 2>&1
+ $output = & $verifierPython -m tools.release --archive "$archive" --platform windows-x64 --edition lite --app-smoke --json-out dist/verification-windows-x64-lite.json 2>&1
$status = $LASTEXITCODE
$output | Tee-Object -FilePath dist/verification-windows-x64-lite.txt
if ($status -ne 0) { exit $status }
@@ -241,6 +245,8 @@ jobs:
- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6
with: { workspaces: app/src-tauri }
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
+ with:
+ version: "0.12.3"
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
with: { python-version: "3.12" }
- id: version
@@ -257,7 +263,7 @@ jobs:
run: |
$archive = "dist/MDFlux_${{ steps.version.outputs.value }}_windows_x64_full.zip"
if (-not (Test-Path -LiteralPath $archive)) { throw "Expected archive not found: $archive" }
- $output = python -m tools.release --archive "$archive" --platform windows-x64 --edition full --json-out dist/verification-windows-x64-full.json 2>&1
+ $output = python -m tools.release --archive "$archive" --platform windows-x64 --edition full --app-smoke --json-out dist/verification-windows-x64-full.json 2>&1
$status = $LASTEXITCODE
$output | Tee-Object -FilePath dist/verification-windows-x64-full.txt
if ($status -ne 0) { exit $status }
@@ -281,7 +287,7 @@ jobs:
with:
ref: "${{ needs.validate-ref.outputs.commit }}"
- name: Install Linux build prerequisites
- run: sudo apt-get update && sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev javascriptcoregtk-4.1-dev patchelf pkg-config build-essential
+ run: sudo apt-get update && sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev javascriptcoregtk-4.1-dev patchelf pkg-config build-essential xvfb
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
with: { node-version: 20, cache: npm, cache-dependency-path: app/package-lock.json }
- name: Install frontend dependencies
@@ -293,6 +299,8 @@ jobs:
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
with: { python-version: "3.12" }
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
+ with:
+ version: "0.12.3"
- id: version
run: |
mkdir -p dist
@@ -307,7 +315,7 @@ jobs:
uv venv --python 3.12 .venv-verifier
uv pip install --python .venv-verifier/bin/python --require-hashes -r app/src-tauri/resources/sidecar/requirements-full.lock
set +e
- .venv-verifier/bin/python -m tools.release --archive "$ARCHIVE" --platform linux-x64-glibc --edition lite --json-out dist/verification-linux-x64-glibc-lite.json 2>&1 | tee dist/verification-linux-x64-glibc-lite.txt
+ xvfb-run -a .venv-verifier/bin/python -m tools.release --archive "$ARCHIVE" --platform linux-x64-glibc --edition lite --app-smoke --json-out dist/verification-linux-x64-glibc-lite.json 2>&1 | tee dist/verification-linux-x64-glibc-lite.txt
status=${PIPESTATUS[0]}
set -e
exit "$status"
@@ -332,7 +340,7 @@ jobs:
with:
ref: "${{ needs.validate-ref.outputs.commit }}"
- name: Install Linux build prerequisites
- run: sudo apt-get update && sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev javascriptcoregtk-4.1-dev patchelf pkg-config build-essential
+ run: sudo apt-get update && sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev javascriptcoregtk-4.1-dev patchelf pkg-config build-essential xvfb
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
with: { node-version: 20, cache: npm, cache-dependency-path: app/package-lock.json }
- name: Install frontend dependencies
@@ -342,6 +350,8 @@ jobs:
- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6
with: { workspaces: app/src-tauri }
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
+ with:
+ version: "0.12.3"
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
with: { python-version: "3.12" }
- id: version
@@ -357,7 +367,7 @@ jobs:
ARCHIVE="dist/MDFlux_${{ steps.version.outputs.value }}_linux_x64_glibc_full.tar.gz"
test -f "$ARCHIVE"
set +e
- python -m tools.release --archive "$ARCHIVE" --platform linux-x64-glibc --edition full --json-out dist/verification-linux-x64-glibc-full.json 2>&1 | tee dist/verification-linux-x64-glibc-full.txt
+ xvfb-run -a python -m tools.release --archive "$ARCHIVE" --platform linux-x64-glibc --edition full --app-smoke --json-out dist/verification-linux-x64-glibc-full.json 2>&1 | tee dist/verification-linux-x64-glibc-full.txt
status=${PIPESTATUS[0]}
set -e
exit "$status"
@@ -387,12 +397,13 @@ jobs:
EXPECTED_COMMIT: "${{ needs.validate-ref.outputs.commit }}"
run: |
python - <<'PY'
- import os
+ import json, os
from pathlib import Path
root = Path('candidate')
+ app_version = json.load(open('app/src-tauri/tauri.conf.json'))['version']
expected = {
- 'MDFlux_0.3.0_windows_x64_lite.zip', 'MDFlux_0.3.0_windows_x64_full.zip',
- 'MDFlux_0.3.0_linux_x64_glibc_lite.tar.gz', 'MDFlux_0.3.0_linux_x64_glibc_full.tar.gz'}
+ f'MDFlux_{app_version}_windows_x64_lite.zip', f'MDFlux_{app_version}_windows_x64_full.zip',
+ f'MDFlux_{app_version}_linux_x64_glibc_lite.tar.gz', f'MDFlux_{app_version}_linux_x64_glibc_full.tar.gz'}
archives = {p.name for p in root.glob('MDFlux_*')}
if archives != expected: raise SystemExit(f'archive set mismatch: {archives}')
commits = {p.read_text().strip() for p in root.glob('source-commit.txt')}
@@ -412,7 +423,8 @@ jobs:
from pathlib import Path
root = Path('candidate')
archives = sorted(p.name for p in root.glob('MDFlux_*'))
- manifest = {'schema': 1, 'kind': 'release-candidate', 'app_version': '0.3.0', 'commit': os.environ['EXPECTED_COMMIT'], 'built_at_utc': datetime.now(timezone.utc).replace(microsecond=0).isoformat(), 'archives': archives, 'platforms': ['windows-x64', 'linux-x64-glibc'], 'editions': ['lite', 'full']}
+ app_version = json.load(open('app/src-tauri/tauri.conf.json'))['version']
+ manifest = {'schema': 1, 'kind': 'release-candidate', 'app_version': app_version, 'commit': os.environ['EXPECTED_COMMIT'], 'built_at_utc': datetime.now(timezone.utc).replace(microsecond=0).isoformat(), 'archives': archives, 'platforms': ['windows-x64', 'linux-x64-glibc'], 'editions': ['lite', 'full']}
(root / 'release-candidate' / 'release-candidate.json').write_text(json.dumps(manifest, indent=2) + '\n', encoding='utf-8')
PY
cp candidate/MDFlux_* candidate/release-candidate/
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 79589e9..f8ee36d 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -87,7 +87,7 @@ jobs:
with:
ref: "${{ needs.validate-tag.outputs.commit }}"
- name: Install Linux build prerequisites
- run: sudo apt-get update && sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev javascriptcoregtk-4.1-dev patchelf pkg-config build-essential
+ run: sudo apt-get update && sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev javascriptcoregtk-4.1-dev patchelf pkg-config build-essential xvfb
- uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c
- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6
with: { workspaces: app/src-tauri }
@@ -105,6 +105,7 @@ jobs:
ref: "${{ needs.validate-tag.outputs.commit }}"
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
with:
+ version: "0.12.3"
enable-cache: true
cache-dependency-glob: |
app/src-tauri/resources/sidecar/requirements.lock
@@ -134,6 +135,7 @@ jobs:
ref: "${{ needs.validate-tag.outputs.commit }}"
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
with:
+ version: "0.12.3"
enable-cache: true
cache-dependency-glob: |
app/src-tauri/resources/sidecar/requirements.lock
@@ -181,6 +183,8 @@ jobs:
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
with: { python-version: "3.12" }
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
+ with:
+ version: "0.12.3"
- id: version
shell: pwsh
run: |
@@ -197,7 +201,7 @@ jobs:
uv venv --python 3.12 .venv-verifier
$verifierPython = (Resolve-Path .venv-verifier/Scripts/python.exe).Path
uv pip install --python $verifierPython --require-hashes -r app/src-tauri/resources/sidecar/requirements-full.lock
- $output = & $verifierPython -m tools.release --archive "$archive" --platform windows-x64 --edition lite --json-out dist/verification-windows-x64-lite.json 2>&1
+ $output = & $verifierPython -m tools.release --archive "$archive" --platform windows-x64 --edition lite --app-smoke --json-out dist/verification-windows-x64-lite.json 2>&1
$status = $LASTEXITCODE
$output | Tee-Object -FilePath dist/verification-windows-x64-lite.txt
if ($status -ne 0) { exit $status }
@@ -230,6 +234,8 @@ jobs:
- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6
with: { workspaces: app/src-tauri }
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
+ with:
+ version: "0.12.3"
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
with: { python-version: "3.12" }
- id: version
@@ -246,7 +252,7 @@ jobs:
run: |
$archive = "dist/MDFlux_${{ steps.version.outputs.value }}_windows_x64_full.zip"
if (-not (Test-Path -LiteralPath $archive)) { throw "Expected archive not found: $archive" }
- $output = python -m tools.release --archive "$archive" --platform windows-x64 --edition full --json-out dist/verification-windows-x64-full.json 2>&1
+ $output = python -m tools.release --archive "$archive" --platform windows-x64 --edition full --app-smoke --json-out dist/verification-windows-x64-full.json 2>&1
$status = $LASTEXITCODE
$output | Tee-Object -FilePath dist/verification-windows-x64-full.txt
if ($status -ne 0) { exit $status }
@@ -270,7 +276,7 @@ jobs:
with:
ref: "${{ needs.validate-tag.outputs.commit }}"
- name: Install Linux build prerequisites
- run: sudo apt-get update && sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev javascriptcoregtk-4.1-dev patchelf pkg-config build-essential
+ run: sudo apt-get update && sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev javascriptcoregtk-4.1-dev patchelf pkg-config build-essential xvfb
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
with: { node-version: 20, cache: npm, cache-dependency-path: app/package-lock.json }
- name: Install frontend dependencies
@@ -282,6 +288,8 @@ jobs:
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
with: { python-version: "3.12" }
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
+ with:
+ version: "0.12.3"
- id: version
run: |
mkdir -p dist
@@ -296,7 +304,7 @@ jobs:
uv venv --python 3.12 .venv-verifier
uv pip install --python .venv-verifier/bin/python --require-hashes -r app/src-tauri/resources/sidecar/requirements-full.lock
set +e
- .venv-verifier/bin/python -m tools.release --archive "$ARCHIVE" --platform linux-x64-glibc --edition lite --json-out dist/verification-linux-x64-glibc-lite.json 2>&1 | tee dist/verification-linux-x64-glibc-lite.txt
+ xvfb-run -a .venv-verifier/bin/python -m tools.release --archive "$ARCHIVE" --platform linux-x64-glibc --edition lite --app-smoke --json-out dist/verification-linux-x64-glibc-lite.json 2>&1 | tee dist/verification-linux-x64-glibc-lite.txt
status=${PIPESTATUS[0]}
set -e
exit "$status"
@@ -321,7 +329,7 @@ jobs:
with:
ref: "${{ needs.validate-tag.outputs.commit }}"
- name: Install Linux build prerequisites
- run: sudo apt-get update && sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev javascriptcoregtk-4.1-dev patchelf pkg-config build-essential
+ run: sudo apt-get update && sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev javascriptcoregtk-4.1-dev patchelf pkg-config build-essential xvfb
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
with: { node-version: 20, cache: npm, cache-dependency-path: app/package-lock.json }
- name: Install frontend dependencies
@@ -331,6 +339,8 @@ jobs:
- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6
with: { workspaces: app/src-tauri }
- uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
+ with:
+ version: "0.12.3"
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
with: { python-version: "3.12" }
- id: version
@@ -346,7 +356,7 @@ jobs:
ARCHIVE="dist/MDFlux_${{ steps.version.outputs.value }}_linux_x64_glibc_full.tar.gz"
test -f "$ARCHIVE"
set +e
- python -m tools.release --archive "$ARCHIVE" --platform linux-x64-glibc --edition full --json-out dist/verification-linux-x64-glibc-full.json 2>&1 | tee dist/verification-linux-x64-glibc-full.txt
+ xvfb-run -a python -m tools.release --archive "$ARCHIVE" --platform linux-x64-glibc --edition full --app-smoke --json-out dist/verification-linux-x64-glibc-full.json 2>&1 | tee dist/verification-linux-x64-glibc-full.txt
status=${PIPESTATUS[0]}
set -e
exit "$status"
@@ -382,7 +392,8 @@ jobs:
import os, json
from pathlib import Path
root = Path('release-assets')
- expected = {'MDFlux_0.3.0_windows_x64_lite.zip', 'MDFlux_0.3.0_windows_x64_full.zip', 'MDFlux_0.3.0_linux_x64_glibc_lite.tar.gz', 'MDFlux_0.3.0_linux_x64_glibc_full.tar.gz'}
+ app_version = json.load(open('app/src-tauri/tauri.conf.json'))['version']
+ expected = {f'MDFlux_{app_version}_windows_x64_lite.zip', f'MDFlux_{app_version}_windows_x64_full.zip', f'MDFlux_{app_version}_linux_x64_glibc_lite.tar.gz', f'MDFlux_{app_version}_linux_x64_glibc_full.tar.gz'}
archives = {p.name for p in root.glob('MDFlux_*')}
if archives != expected: raise SystemExit(f'archive set mismatch: {archives}')
commits = {p.read_text().strip() for p in root.glob('source-commit.txt')}
@@ -404,7 +415,8 @@ jobs:
from pathlib import Path
root = Path('release-assets')
archives = sorted(p.name for p in root.glob('MDFlux_*'))
- manifest = {'schema': 1, 'kind': 'release', 'app_version': '0.3.0', 'commit': os.environ['EXPECTED_COMMIT'], 'tag': os.environ['RELEASE_TAG'], 'built_at_utc': datetime.now(timezone.utc).replace(microsecond=0).isoformat(), 'archives': archives, 'platforms': ['windows-x64', 'linux-x64-glibc'], 'editions': ['lite', 'full']}
+ app_version = json.load(open('app/src-tauri/tauri.conf.json'))['version']
+ manifest = {'schema': 1, 'kind': 'release', 'app_version': app_version, 'commit': os.environ['EXPECTED_COMMIT'], 'tag': os.environ['RELEASE_TAG'], 'built_at_utc': datetime.now(timezone.utc).replace(microsecond=0).isoformat(), 'archives': archives, 'platforms': ['windows-x64', 'linux-x64-glibc'], 'editions': ['lite', 'full']}
(root / 'manifest' / 'release-manifest.json').write_text(json.dumps(manifest, indent=2) + '\n', encoding='utf-8')
PY
cp release-assets/MDFlux_* release-assets/manifest/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b298dc4..34ec231 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,29 @@ All notable changes to this project are documented here. The format is based on
## [Unreleased]
+## [0.3.1] - Unreleased
+
+### Fixed
+
+- Lite editions could not complete first-run setup on Windows and Linux: the app downloaded
+ uv 0.5.11 while the shipped lockfiles are compiled with uv 0.12 (`--require-hashes` failed
+ with "all requirements must be pinned upfront ... found: tzdata"). The app now installs the
+ same uv 0.12.3 that CI validates the lockfiles with, and CI fails if the two ever drift (#57).
+- Linux portable archives failed to start with "requirements.lock not found at
+ /usr/lib/MDFlux/..." unless they were symlinked into the system location. Resources are now
+ resolved next to the executable, so the archive runs from any directory (#53).
+- Diagnostics reported HTTP 403 for valid Groq keys because the probe sent Python's default
+ user agent. Every provider request now identifies as `MDFlux/<version>` (#25).
+- Lite installs a versioned uv into `app-data/bin/uv-<version>/` through a staging directory,
+ so a half-downloaded or obsolete installer is never reused.
+
+### Changed
+
+- Release and release-candidate workflows launch each packaged archive in an isolated
+ package-verification mode (`--app-smoke`): first run, restart, and relocation of the payload
+ must pass before an archive can be published. Expected archive names are derived from the
+ application version instead of being hard-coded.
+
## [0.3.0] - 2026-08-23
### Added
diff --git a/README.md b/README.md
index 4d7dfd3..71cbc26 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ Local-first · reads scanned PDFs · up to 6× fewer tokens than vision models
**Works with** PDF · DOCX · PPTX · XLSX · EPUB · HTML · CSV · JSON · XML · TXT · MD · images · audio
[![License: MIT](https://img.shields.io/badge/License-MIT-3b82f6.svg)](LICENSE)
-[![Download v0.3.0](https://img.shields.io/badge/download-v0.3.0-3b82f6)](https://github.com/ibrahimqureshae/mdflux/releases/latest)
+[![Download v0.3.1](https://img.shields.io/badge/download-v0.3.1-3b82f6)](https://github.com/ibrahimqureshae/mdflux/releases/latest)
[![Up to 6x fewer tokens](https://img.shields.io/badge/vs%20vision-up%20to%206%C3%97%20fewer%20tokens-3b82f6)](#the-proof-fewer-tokens-lower-cost)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20(x64)-3b82f6.svg)](https://github.com/ibrahimqureshae/mdflux/releases)
[![Works offline](https://img.shields.io/badge/works-offline-3fb950)](#)
@@ -40,25 +40,25 @@ For the easiest setup, download **Full**. Everything needed for document convers
<div align="center">
-<a href="https://github.com/ibrahimqureshae/mdflux/releases/latest/download/MDFlux_0.3.0_windows_x64_full.zip">
+<a href="https://github.com/ibrahimqureshae/mdflux/releases/latest/download/MDFlux_0.3.1_windows_x64_full.zip">
<img src="docs/media/download/windows-full.svg" width="400" alt="Download MDFlux Full for Windows">
</a>
-<a href="https://github.com/ibrahimqureshae/mdflux/releases/latest/download/MDFlux_0.3.0_linux_x64_glibc_full.tar.gz">
+<a href="https://github.com/ibrahimqureshae/mdflux/releases/latest/download/MDFlux_0.3.1_linux_x64_glibc_full.tar.gz">
<img src="docs/media/download/linux-full.svg" width="400" alt="Download MDFlux Full for Linux">
</a>
-[![Download for Windows](https://img.shields.io/badge/Download_for_Windows-Lite_x64-2563EB?style=for-the-badge&logo=windows11&logoColor=white)](https://github.com/ibrahimqureshae/mdflux/releases/latest/download/MDFlux_0.3.0_windows_x64_lite.zip)
+[![Download for Windows](https://img.shields.io/badge/Download_for_Windows-Lite_x64-2563EB?style=for-the-badge&logo=windows11&logoColor=white)](https://github.com/ibrahimqureshae/mdflux/releases/latest/download/MDFlux_0.3.1_windows_x64_lite.zip)
&nbsp;&nbsp;
-[![Download for Linux](https://img.shields.io/badge/Download_for_Linux-Lite_x64-F59E0B?style=for-the-badge&logo=linux&logoColor=white)](https://github.com/ibrahimqureshae/mdflux/releases/latest/download/MDFlux_0.3.0_linux_x64_glibc_lite.tar.gz)
+[![Download for Linux](https://img.shields.io/badge/Download_for_Linux-Lite_x64-F59E0B?style=for-the-badge&logo=linux&logoColor=white)](https://github.com/ibrahimqureshae/mdflux/releases/latest/download/MDFlux_0.3.1_linux_x64_glibc_lite.tar.gz)
**Not sure which edition to choose? Download Full.**
Everything is packaged together, so there are no additional MDFlux setup downloads when you open it.
Prefer a smaller first download?
-[Windows Lite (4.9 MB)](https://github.com/ibrahimqureshae/mdflux/releases/latest/download/MDFlux_0.3.0_windows_x64_lite.zip) ·
-[Linux Lite (5.8 MB)](https://github.com/ibrahimqureshae/mdflux/releases/latest/download/MDFlux_0.3.0_linux_x64_glibc_lite.tar.gz)
+[Windows Lite (4.9 MB)](https://github.com/ibrahimqureshae/mdflux/releases/latest/download/MDFlux_0.3.1_windows_x64_lite.zip) ·
+[Linux Lite (5.8 MB)](https://github.com/ibrahimqureshae/mdflux/releases/latest/download/MDFlux_0.3.1_linux_x64_glibc_lite.tar.gz)
Lite downloads and installs the required components when you first open it.
diff --git a/ROADMAP.md b/ROADMAP.md
index 1f9c48f..5a3dfcb 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -9,20 +9,23 @@ are welcome; open one to help shape priorities.
- Improve stability and diagnostics based on user reports.
- Keep Lite and Full portable releases reliable and easy to verify.
+## Shipped in 0.3.0
+
+- Windows x64 Lite and Full portable zips.
+- Linux x64 glibc Lite and Full tarballs, with consistent release metadata and verification.
+
## Planned
-- Linux x64 glibc Lite and Full tarballs.
-- Windows Lite and Full portable zips with consistent release metadata.
- An MCP server and a scriptable, headless `mdflux convert` command.
- macOS builds for Apple Silicon and Intel.
- Windows code signing and macOS notarization.
-- An optional reproducible contributor shell using devenv.
## Exploring
- More OCR languages and tuning presets.
- Optional structured outputs such as front matter and JSON sidecars.
- Pluggable cleanup profiles.
+- An optional reproducible contributor shell using devenv (a [devenv](docs/cross-platform/setup-devenv.md) setup already exists; tightening it is still open).
## Out of scope by design
diff --git a/app/package-lock.json b/app/package-lock.json
index 8bf0c86..433c63a 100644
--- a/app/package-lock.json
+++ b/app/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "app",
- "version": "0.3.0",
+ "version": "0.3.1",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "app",
- "version": "0.3.0",
+ "version": "0.3.1",
"license": "MIT",
"dependencies": {
"@fontsource-variable/inter": "^5.2.8",
diff --git a/app/package.json b/app/package.json
index b322ae2..9c29b6d 100644
--- a/app/package.json
+++ b/app/package.json
@@ -1,6 +1,6 @@
{
"name": "app",
- "version": "0.3.0",
+ "version": "0.3.1",
"description": "",
"type": "module",
"scripts": {
diff --git a/app/src-tauri/Cargo.lock b/app/src-tauri/Cargo.lock
index c06a04f..8f75ba8 100644
--- a/app/src-tauri/Cargo.lock
+++ b/app/src-tauri/Cargo.lock
@@ -60,7 +60,7 @@ checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
[[package]]
name = "app"
-version = "0.3.0"
+version = "0.3.1"
dependencies = [
"flate2",
"reqwest 0.12.28",
diff --git a/app/src-tauri/Cargo.toml b/app/src-tauri/Cargo.toml
index 6e99ed1..76072f3 100644
--- a/app/src-tauri/Cargo.toml
+++ b/app/src-tauri/Cargo.toml
@@ -1,6 +1,6 @@
[package]
name = "app"
-version = "0.3.0"
+version = "0.3.1"
description = "MDFlux"
authors = []
edition = "2021"
diff --git a/app/src-tauri/resources/sidecar/provider.py b/app/src-tauri/resources/sidecar/provider.py
index 236fde4..dba2c0b 100644
--- a/app/src-tauri/resources/sidecar/provider.py
+++ b/app/src-tauri/resources/sidecar/provider.py
@@ -13,6 +13,7 @@ Rule across both groups: never log or mention the API key in any return value.
"""
import asyncio
import json
+import os
import urllib.error
import urllib.request
@@ -43,6 +44,20 @@ def _safe_exc(exc: Exception) -> str:
return f"{type(exc).__name__}: {exc}"
+def _user_agent() -> str:
+ """Identify MDFlux on every provider request.
+
+ Some provider edges (Groq, 2026-10) answer Python's default `Python-urllib`
+ agent with HTTP 403 before the key is even checked, which made the
+ Diagnostics probe fail for working keys (#25).
+ """
+ return f"MDFlux/{os.environ.get('MDFLUX_APP_VERSION', 'dev')}"
+
+
+def _client(timeout: httpx.Timeout) -> httpx.AsyncClient:
+ return httpx.AsyncClient(timeout=timeout, headers={"User-Agent": _user_agent()})
+
+
def check_local(base_url: str) -> dict:
"""
Probe a local server at base_url.
@@ -137,7 +152,7 @@ def check_openai_compat(base_url: str, key: str) -> dict:
base = base_url.rstrip("/")
req = urllib.request.Request(
f"{base}/models",
- headers={"Authorization": f"Bearer {key}"},
+ headers={"Authorization": f"Bearer {key}", "User-Agent": _user_agent()},
)
try:
with urllib.request.urlopen(req, timeout=8) as r:
@@ -186,6 +201,7 @@ def check_anthropic(key: str) -> dict:
headers={
"x-api-key": key,
"anthropic-version": "2023-06-01",
+ "User-Agent": _user_agent(),
},
)
try:
@@ -310,7 +326,7 @@ async def _post_json_async(
) -> dict:
_check_cancelled(cancel_event)
try:
- async with httpx.AsyncClient(timeout=_timeout(timeout)) as client:
+ async with _client(_timeout(timeout)) as client:
response = await client.post(url, headers=headers, json=payload)
await _raise_http_error(response)
_check_cancelled(cancel_event)
@@ -371,7 +387,7 @@ async def _stream_openai(
) -> str:
pieces: list[str] = []
try:
- async with httpx.AsyncClient(timeout=_timeout(idle_timeout)) as client:
+ async with _client(_timeout(idle_timeout)) as client:
async with client.stream("POST", url, headers=headers, json=payload) as response:
await _raise_http_error(response)
content_type = response.headers.get("content-type", "").lower()
@@ -497,7 +513,7 @@ async def chat_ollama(
}
pieces: list[str] = []
try:
- async with httpx.AsyncClient(timeout=_timeout(idle_timeout)) as client:
+ async with _client(_timeout(idle_timeout)) as client:
async with client.stream(
"POST", f"{base}/api/chat",
headers={"Content-Type": "application/json"}, json=payload,
@@ -605,7 +621,7 @@ async def chat_anthropic(
}
pieces: list[str] = []
try:
- async with httpx.AsyncClient(timeout=_timeout(idle_timeout)) as client:
+ async with _client(_timeout(idle_timeout)) as client:
async with client.stream(
"POST", "https://api.anthropic.com/v1/messages",
headers=headers, json=payload,
diff --git a/app/src-tauri/resources/sidecar/tests/test_provider_user_agent.py b/app/src-tauri/resources/sidecar/tests/test_provider_user_agent.py
new file mode 100644
index 0000000..a4adfa2
--- /dev/null
+++ b/app/src-tauri/resources/sidecar/tests/test_provider_user_agent.py
@@ -0,0 +1,84 @@
+import asyncio
+import json
+import os
+import sys
+import unittest
+import urllib.request
+from pathlib import Path
+from unittest import mock
+
+
+SIDECAR_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SIDECAR_DIR))
+
+import provider # noqa: E402
+
+
+class UserAgentTests(unittest.TestCase):
+ def test_user_agent_carries_app_version(self):
+ with mock.patch.dict(os.environ, {"MDFLUX_APP_VERSION": "9.9.9"}):
+ self.assertEqual(provider._user_agent(), "MDFlux/9.9.9")
+ with mock.patch.dict(os.environ, {}, clear=True):
+ self.assertEqual(provider._user_agent(), "MDFlux/dev")
+
+ def test_openai_compat_probe_sends_mdflux_user_agent(self):
+ seen = {}
+
+ def fake_urlopen(req, timeout=0):
+ seen["ua"] = req.get_header("User-agent")
+ raise urllib.error.HTTPError(req.full_url, 401, "Unauthorized", {}, None)
+
+ with mock.patch.object(urllib.request, "urlopen", fake_urlopen):
+ provider.check_openai_compat("https://api.groq.com/openai/v1", "k")
+ self.assertTrue(seen["ua"].startswith("MDFlux/"), seen)
+
+ def test_anthropic_probe_sends_mdflux_user_agent(self):
+ seen = {}
+
+ def fake_urlopen(req, timeout=0):
+ seen["ua"] = req.get_header("User-agent")
+ raise urllib.error.HTTPError(req.full_url, 401, "Unauthorized", {}, None)
+
+ with mock.patch.object(urllib.request, "urlopen", fake_urlopen):
+ provider.check_anthropic("sk-ant-test")
+ self.assertTrue(seen["ua"].startswith("MDFlux/"), seen)
+
+
+class ChatUserAgentTests(unittest.IsolatedAsyncioTestCase):
+ async def test_chat_request_sends_mdflux_user_agent(self):
+ seen = {}
+
+ async def handle(reader, writer):
+ head = await reader.readuntil(b"\r\n\r\n")
+ length = 0
+ for line in head.decode(errors="replace").split("\r\n"):
+ low = line.lower()
+ if low.startswith("content-length:"):
+ length = int(line.split(":", 1)[1].strip())
+ if low.startswith("user-agent:"):
+ seen["ua"] = line.split(":", 1)[1].strip()
+ if length:
+ await reader.readexactly(length)
+ body = json.dumps({"choices": [{"message": {"content": "ok"}}]}).encode()
+ writer.write(
+ b"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\n"
+ + f"Content-Length: {len(body)}\r\n\r\n".encode() + body
+ )
+ await writer.drain()
+ writer.close()
+
+ server = await asyncio.start_server(handle, "127.0.0.1", 0)
+ port = server.sockets[0].getsockname()[1]
+ try:
+ text = await provider.chat_openai_compat(
+ f"http://127.0.0.1:{port}/v1", "", "m", "sys", "user", idle_timeout=5,
+ )
+ finally:
+ server.close()
+ await server.wait_closed()
+ self.assertEqual(text, "ok")
+ self.assertTrue(seen.get("ua", "").startswith("MDFlux/"), seen)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/app/src-tauri/src/ipc.rs b/app/src-tauri/src/ipc.rs
index 7454d92..81da4d1 100644
--- a/app/src-tauri/src/ipc.rs
+++ b/app/src-tauri/src/ipc.rs
@@ -32,7 +32,7 @@ pub struct ProgressPayload {
/// What is being downloaded right now, and how fast.
#[derive(Debug, Serialize, Clone)]
pub struct DownloadDetail {
- /// Human label for the artefact, e.g. "uv 0.5.11 (Windows x64)".
+ /// Human label for the artefact, e.g. "uv 0.12.3 - Python package manager (Windows x64)".
pub label: String,
/// Bytes received so far.
pub received: u64,
diff --git a/app/src-tauri/src/lib.rs b/app/src-tauri/src/lib.rs
index 9062970..ea57129 100644
--- a/app/src-tauri/src/lib.rs
+++ b/app/src-tauri/src/lib.rs
@@ -2,6 +2,7 @@ mod bootstrap;
mod config;
mod converter;
mod ipc;
+mod package_verification;
mod platform;
mod runtime;
@@ -112,10 +113,7 @@ impl BatchManager {
fn sidecar_paths(app: &AppHandle) -> Result<(PathBuf, PathBuf), String> {
let python = bootstrap::python_path(app)?;
- let resource_dir = app
- .path()
- .resource_dir()
- .map_err(|e| format!("Cannot locate app resources: {e}"))?;
+ let resource_dir = runtime::RuntimeContext::resolve(app)?.resource_root;
let script = resource_dir
.join("resources")
.join("sidecar")
@@ -2123,12 +2121,23 @@ mod tests {
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
+ let verification = package_verification::Verification::from_args().unwrap_or_else(|error| {
+ eprintln!("{error}");
+ std::process::exit(2);
+ });
+ let mut context = tauri::generate_context!();
+ if verification.0.is_some() {
+ context.config_mut().app.windows.clear();
+ }
// Per-worker CPU-thread budget for batch conversions. The sidecar reads this and
// applies it to batch workers only (single conversions use all cores). Set once at
// startup so it propagates to the sidecar process and its worker subprocesses.
std::env::set_var("MDFLUX_BATCH_THREADS", batch_worker_threads().to_string());
+ // The sidecar identifies itself to AI providers as MDFlux/<version> (#25).
+ std::env::set_var("MDFLUX_APP_VERSION", env!("CARGO_PKG_VERSION"));
let app = tauri::Builder::default()
+ .manage(verification)
.manage(Arc::new(SidecarManager::new()))
.manage(Arc::new(BatchManager::new()))
.manage(Arc::new(WrittenPaths::default()))
@@ -2137,6 +2146,24 @@ pub fn run() {
.plugin(tauri_plugin_dialog::init())
.plugin(tauri_plugin_fs::init())
.setup(|app| {
+ if let Some(root) = app.state::<package_verification::Verification>().0.clone() {
+ let handle = app.handle().clone();
+ tauri::async_runtime::spawn(async move {
+ let result = package_verification::run(&handle, &root).await;
+ handle.state::<Arc<SidecarManager>>().kill_sidecar().await;
+ let passed = result.is_ok();
+ let report = result.unwrap_or_else(
+ |error| serde_json::json!({"passed": false, "error": error}),
+ );
+ let written = std::fs::write(
+ root.join("report.json"),
+ serde_json::to_vec_pretty(&report).unwrap(),
+ )
+ .is_ok();
+ handle.exit(if passed && written { 0 } else { 1 });
+ });
+ return Ok(());
+ }
if let Err(e) = bootstrap::on_successful_launch(app.handle()) {
eprintln!("runtime prune skipped: {e}");
}
@@ -2167,7 +2194,7 @@ pub fn run() {
optional_engine_status,
install_engine,
])
- .build(tauri::generate_context!())
+ .build(context)
.expect("error while building tauri application");
// Kill the sidecar deterministically on app exit. kill_on_drop(true) on the spawn
diff --git a/app/src-tauri/src/package_verification.rs b/app/src-tauri/src/package_verification.rs
new file mode 100644
index 0000000..b1b12c2
--- /dev/null
+++ b/app/src-tauri/src/package_verification.rs
@@ -0,0 +1,73 @@
+//! Explicit packaged-backend smoke mode. Never uses the user's application data.
+use std::{path::PathBuf, sync::Arc};
+use tauri::Manager;
+
+#[derive(Clone, Default)]
+pub struct Verification(pub Option<PathBuf>);
+
+impl Verification {
+ pub fn from_args() -> Result<Self, String> {
+ let args: Vec<_> = std::env::args_os().collect();
+ if args.get(1).is_none_or(|arg| arg != "--verify-package") {
+ return Ok(Self::default());
+ }
+ if args.len() != 3 {
+ return Err("Usage: MDFlux --verify-package ABSOLUTE_TEST_DIRECTORY".into());
+ }
+ let path = PathBuf::from(&args[2]);
+ if !path.is_absolute() {
+ return Err("Verification directory must be absolute".into());
+ }
+ let marker = path.join(".mdflux-verification");
+ if path.exists() && !marker.is_file() {
+ return Err("Refusing an existing directory without a verification marker".into());
+ }
+ std::fs::create_dir_all(&path).map_err(|e| e.to_string())?;
+ std::fs::write(marker, "MDFlux isolated package verification\n")
+ .map_err(|e| e.to_string())?;
+ Ok(Self(Some(path)))
+ }
+}
+
+pub async fn run(
+ app: &tauri::AppHandle,
+ root: &std::path::Path,
+) -> Result<serde_json::Value, String> {
+ let ctx = crate::runtime::RuntimeContext::resolve(app)?;
+ let manager = app.state::<Arc<crate::SidecarManager>>();
+ let mgr = Arc::clone(&manager);
+ // Full must work without provisioning; Lite exercises the real installer.
+ if !ctx.is_full() {
+ crate::runtime::provision(app.clone(), false, || async move {
+ mgr.kill_sidecar().await;
+ })
+ .await?;
+ }
+ let health = crate::run_health_check(app.clone(), app.state()).await?;
+ let (python, script) = crate::sidecar_paths(app)?;
+ let fixture = root.join("smoke.txt");
+ let expected = "MDFlux packaged runtime regression fixture";
+ std::fs::write(&fixture, expected).map_err(|e| e.to_string())?;
+ let response = manager
+ .send_streaming(
+ &serde_json::json!({
+ "v": 1, "id": "package-smoke", "method": "convert-one", "params": {"path": fixture}
+ }),
+ |_| {},
+ )
+ .await?;
+ if response.get("ok").and_then(|v| v.as_bool()) != Some(true)
+ || !response["result"]["markdown"]
+ .as_str()
+ .unwrap_or("")
+ .contains(expected)
+ {
+ return Err(format!("Packaged conversion failed: {response}"));
+ }
+ Ok(
+ serde_json::json!({"passed": true, "edition": ctx.edition_kind().as_str(),
+ "resource_root": ctx.resource_root, "app_data": ctx.app_data, "python": python,
+ "sidecar": script, "health": health, "conversion": "text fixture passed",
+ "uv_version": crate::platform::UV_VERSION}),
+ )
+}
diff --git a/app/src-tauri/src/platform/mod.rs b/app/src-tauri/src/platform/mod.rs
index 0e33d16..b5668d8 100644
--- a/app/src-tauri/src/platform/mod.rs
+++ b/app/src-tauri/src/platform/mod.rs
@@ -5,6 +5,9 @@
use std::path::Path;
+// Keep application provisioning and CI on the same lockfile-compatible installer.
+pub const UV_VERSION: &str = "0.12.3";
+
/// Platform identifiers supported by the application.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PlatformId {
@@ -49,13 +52,13 @@ pub fn current_platform() -> Result<PlatformSpec, String> {
Ok(PlatformSpec {
id: PlatformId::WindowsX64,
uv_url:
- "https://github.com/astral-sh/uv/releases/download/0.5.11/uv-x86_64-pc-windows-msvc.zip",
- uv_sha256: "3e8203e6434b45427f20824419f8d8d53f970a76d94ccdcad07f8498fa01a9d0",
+ "https://github.com/astral-sh/uv/releases/download/0.12.3/uv-x86_64-pc-windows-msvc.zip",
+ uv_sha256: "b23350c79e8ad0192b8124af13a0f17e8d4e4549524785e1aef389ae5a06990e",
uv_archive: "uv.zip",
uv_bin: "uv.exe",
venv_python_bin: "Scripts/python.exe",
bundled_python_bin: "python.exe",
- uv_label: "uv 0.5.11 - Python package manager (Windows x64)",
+ uv_label: "uv 0.12.3 - Python package manager (Windows x64)",
})
}
@@ -63,13 +66,13 @@ pub fn current_platform() -> Result<PlatformSpec, String> {
pub fn current_platform() -> Result<PlatformSpec, String> {
Ok(PlatformSpec {
id: PlatformId::LinuxX64Glibc,
- uv_url: "https://github.com/astral-sh/uv/releases/download/0.5.11/uv-x86_64-unknown-linux-gnu.tar.gz",
- uv_sha256: "14411de26cdea5f5139fafaf2b675b1c633e744dd49c6d6a9fc8817ec065158b",
+ uv_url: "https://github.com/astral-sh/uv/releases/download/0.12.3/uv-x86_64-unknown-linux-gnu.tar.gz",
+ uv_sha256: "600cf9a742aca00d292673b16b5acffaa7b8c269a364ad0c2e79498dcb1fe101",
uv_archive: "uv.tar.gz",
uv_bin: "uv",
venv_python_bin: "bin/python",
bundled_python_bin: "bin/python3",
- uv_label: "uv 0.5.11 - Python package manager (Linux x64)",
+ uv_label: "uv 0.12.3 - Python package manager (Linux x64)",
})
}
diff --git a/app/src-tauri/src/runtime/manager.rs b/app/src-tauri/src/runtime/manager.rs
index 49fc176..e1291ed 100644
--- a/app/src-tauri/src/runtime/manager.rs
+++ b/app/src-tauri/src/runtime/manager.rs
@@ -55,15 +55,18 @@ pub struct RuntimeContext {
impl RuntimeContext {
pub fn resolve(app: &AppHandle) -> Result<Self, String> {
let platform = platform::current_platform()?;
- let resource_root = app
+ let framework_root = app
.path()
.resource_dir()
.map_err(|e| format!("Cannot locate app resources: {e}"))?;
+ let executable = std::env::current_exe().map_err(|e| e.to_string())?;
+ let resource_root =
+ super::resources::resolve(&executable, &framework_root, cfg!(debug_assertions))?;
let edition = match EditionManifest::load(&resource_root, &platform)? {
Some(m) => EffectiveEdition::Manifest(m),
None => EffectiveEdition::DevLite,
};
- let app_data = app.path().app_data_dir().expect("app data dir unavailable");
+ let app_data = app_data_dir(app);
Ok(Self {
platform,
edition,
@@ -82,6 +85,11 @@ impl RuntimeContext {
}
pub fn app_data_dir(app: &AppHandle) -> PathBuf {
+ if let Some(verification) = app.try_state::<crate::package_verification::Verification>() {
+ if let Some(root) = &verification.0 {
+ return root.join("app-data");
+ }
+ }
app.path().app_data_dir().expect("app data dir unavailable")
}
@@ -529,10 +537,7 @@ pub async fn install_optional_engine(app: AppHandle, engine: String) -> Result<(
other => return Err(format!("Unknown engine: {other}")),
};
- let uv_path = legacy_bin_dir(&ctx.app_data).join(&ctx.platform.uv_bin);
- if !uv_path.exists() {
- return Err("Setup tools not found. Restart the app to re-provision.".into());
- }
+ let uv_path = download_uv(&app, &legacy_bin_dir(&ctx.app_data), &ctx.platform).await?;
let python = python_path(&app)?;
let lock_path = sidecar_resource(&ctx, lock_name)?;
diff --git a/app/src-tauri/src/runtime/mod.rs b/app/src-tauri/src/runtime/mod.rs
index c1edc6b..d693ba7 100644
--- a/app/src-tauri/src/runtime/mod.rs
+++ b/app/src-tauri/src/runtime/mod.rs
@@ -1,6 +1,7 @@
pub mod edition;
pub mod manager;
pub mod provision;
+pub mod resources;
pub mod status;
pub mod store;
diff --git a/app/src-tauri/src/runtime/provision.rs b/app/src-tauri/src/runtime/provision.rs
index ddcc3ae..39a16ac 100644
--- a/app/src-tauri/src/runtime/provision.rs
+++ b/app/src-tauri/src/runtime/provision.rs
@@ -11,6 +11,31 @@ use tauri::{AppHandle, Emitter};
use crate::ipc::{DownloadDetail, ProgressPayload};
use crate::platform::{self, PlatformSpec};
+fn cached_uv_path(bin_dir: &Path, spec: &PlatformSpec) -> PathBuf {
+ bin_dir
+ .join(format!("uv-{}", platform::UV_VERSION))
+ .join(spec.uv_bin)
+}
+
+fn is_expected_uv(path: &Path) -> bool {
+ let mut cmd = std::process::Command::new(path);
+ cmd.arg("--version");
+ #[cfg(windows)]
+ {
+ use std::os::windows::process::CommandExt;
+ cmd.creation_flags(0x08000000);
+ }
+ cmd.output()
+ .map(|output| {
+ output.status.success()
+ && String::from_utf8_lossy(&output.stdout)
+ .split_whitespace()
+ .take(2)
+ .eq(["uv", platform::UV_VERSION])
+ })
+ .unwrap_or(false)
+}
+
pub fn emit_progress(app: &AppHandle, step: &str, message: &str, pct: f32) {
let _ = app.emit(
"provision:progress",
@@ -42,14 +67,10 @@ pub async fn download_uv(
) -> Result<PathBuf, String> {
fs::create_dir_all(bin_dir).map_err(|e| e.to_string())?;
- let uv_path = bin_dir.join(spec.uv_bin);
- if uv_path.exists() {
- let valid = fs::metadata(&uv_path)
- .map(|m| m.len() > 1024)
- .unwrap_or(false);
- if valid {
- return Ok(uv_path);
- }
+ // A legacy bin/uv executable must never satisfy the new installer contract.
+ let uv_path = cached_uv_path(bin_dir, spec);
+ if is_expected_uv(&uv_path) {
+ return Ok(uv_path);
}
let client = reqwest::Client::builder()
@@ -124,19 +145,64 @@ pub async fn download_uv(
}
}
- let archive_path = bin_dir.join(spec.uv_archive);
+ let nonce = std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .map_err(|e| e.to_string())?
+ .as_nanos();
+ let stage = bin_dir.join(format!(
+ "uv-{}.staging-{}-{nonce}",
+ platform::UV_VERSION,
+ std::process::id()
+ ));
+ fs::create_dir(&stage).map_err(|e| e.to_string())?;
+ let archive_path = stage.join(spec.uv_archive);
fs::write(&archive_path, &bytes).map_err(|e| e.to_string())?;
- let dest = bin_dir.to_path_buf();
+ let dest = stage.clone();
let archive_clone = archive_path.clone();
let spec_uv_bin = spec.uv_bin.to_string();
tokio::task::spawn_blocking(move || extract_uv(&archive_clone, &dest, &spec_uv_bin))
.await
.map_err(|e| e.to_string())??;
let _ = fs::remove_file(&archive_path);
- platform::set_executable(&uv_path)?;
+ let staged_uv = stage.join(spec.uv_bin);
+ platform::set_executable(&staged_uv)?;
+ if !is_expected_uv(&staged_uv) {
+ return Err("Downloaded setup tool does not report the pinned uv version.".into());
+ }
+ let destination = uv_path.parent().ok_or("Invalid installer destination")?;
+ // Publish only a fully extracted, hash-verified, executable tool. Preserve
+ // corrupt/obsolete directories for diagnosis rather than overwriting in place.
+ if destination.exists() {
+ if is_expected_uv(&uv_path) {
+ let _ = fs::remove_dir_all(&stage);
+ return Ok(uv_path);
+ }
+ fs::rename(destination, bin_dir.join(format!("uv-invalid-{nonce}")))
+ .map_err(|e| format!("Cannot quarantine invalid setup tools: {e}"))?;
+ }
+ fs::rename(&stage, destination).map_err(|e| format!("Cannot activate setup tools: {e}"))?;
Ok(uv_path)
}
+#[cfg(test)]
+mod installer_tests {
+ use super::*;
+ #[test]
+ fn old_unversioned_installer_is_not_reused() {
+ let spec = platform::current_platform().unwrap();
+ let root = Path::new("fixture-bin");
+ assert_ne!(cached_uv_path(root, &spec), root.join(spec.uv_bin));
+ assert_eq!(
+ cached_uv_path(root, &spec),
+ root.join("uv-0.12.3").join(spec.uv_bin)
+ );
+ }
+ #[test]
+ fn absent_installer_is_not_valid() {
+ assert!(!is_expected_uv(Path::new("nonexistent-mdflux-uv")));
+ }
+}
+
#[cfg(target_os = "windows")]
fn extract_uv(archive: &Path, dest: &Path, uv_bin: &str) -> Result<(), String> {
let file = fs::File::open(archive).map_err(|e| e.to_string())?;
diff --git a/app/src-tauri/src/runtime/resources.rs b/app/src-tauri/src/runtime/resources.rs
new file mode 100644
index 0000000..c8cb65c
--- /dev/null
+++ b/app/src-tauri/src/runtime/resources.rs
@@ -0,0 +1,105 @@
+//! Resolve portable and installed resources once for every runtime consumer.
+use std::path::{Path, PathBuf};
+
+pub fn resolve(
+ executable: &Path,
+ framework_root: &Path,
+ development: bool,
+) -> Result<PathBuf, String> {
+ let adjacent = executable
+ .parent()
+ .ok_or("Executable has no parent directory")?;
+ // A portable payload takes precedence over an unrelated system installation.
+ let root = if adjacent.join("resources").exists() {
+ adjacent
+ } else {
+ framework_root
+ };
+ let resources = root.join("resources");
+ for file in ["sidecar/main.py", "sidecar/requirements.lock"] {
+ if !resources.join(file).is_file() {
+ return Err(format!("Packaged resource {file} is missing under {}. Extract the complete archive before starting MDFlux.", resources.display()));
+ }
+ }
+ if !development && !resources.join("edition.json").is_file() {
+ return Err(format!("Packaged edition manifest is missing under {}. Extract the complete archive before starting MDFlux.", resources.display()));
+ }
+ Ok(root.to_path_buf())
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::{
+ fs,
+ sync::atomic::{AtomicU64, Ordering},
+ };
+ static NEXT: AtomicU64 = AtomicU64::new(0);
+ struct Fixture(PathBuf);
+ impl Fixture {
+ fn new() -> Self {
+ let root = std::env::temp_dir().join(format!(
+ "mdflux-resources-{}-{}",
+ std::process::id(),
+ NEXT.fetch_add(1, Ordering::Relaxed)
+ ));
+ fs::create_dir_all(&root).unwrap();
+ Self(root)
+ }
+ fn payload(&self, name: &str, manifest: bool) -> PathBuf {
+ let root = self.0.join(name);
+ fs::create_dir_all(root.join("resources/sidecar")).unwrap();
+ for file in ["main.py", "requirements.lock"] {
+ fs::write(root.join("resources/sidecar").join(file), "fixture").unwrap();
+ }
+ if manifest {
+ fs::write(root.join("resources/edition.json"), "{}").unwrap();
+ }
+ root
+ }
+ }
+ impl Drop for Fixture {
+ fn drop(&mut self) {
+ let _ = fs::remove_dir_all(&self.0);
+ }
+ }
+ #[test]
+ fn portable_wins_over_system_and_survives_relocation() {
+ let f = Fixture::new();
+ let portable = f.payload("portable with spaces", true);
+ let installed = f.payload("system", true);
+ assert_eq!(
+ resolve(&portable.join("MDFlux"), &installed, false).unwrap(),
+ portable
+ );
+ let moved = f.0.join("relocated");
+ fs::rename(&portable, &moved).unwrap();
+ assert_eq!(
+ resolve(&moved.join("MDFlux"), &installed, false).unwrap(),
+ moved
+ );
+ }
+ #[test]
+ fn installed_layout_uses_framework_root() {
+ let f = Fixture::new();
+ let installed = f.payload("usr/lib/MDFlux", true);
+ assert_eq!(
+ resolve(&f.0.join("usr/bin/MDFlux"), &installed, false).unwrap(),
+ installed
+ );
+ }
+ #[test]
+ fn incomplete_portable_does_not_fall_back_to_system_or_development() {
+ let f = Fixture::new();
+ let portable = f.payload("portable", false);
+ let installed = f.payload("system", true);
+ assert!(resolve(&portable.join("MDFlux"), &installed, false)
+ .unwrap_err()
+ .contains("manifest"));
+ assert!(resolve(&portable.join("MDFlux"), &installed, true).is_ok());
+ fs::remove_file(portable.join("resources/sidecar/requirements.lock")).unwrap();
+ assert!(resolve(&portable.join("MDFlux"), &installed, false)
+ .unwrap_err()
+ .contains("requirements.lock"));
+ }
+}
diff --git a/app/src-tauri/tauri.conf.json b/app/src-tauri/tauri.conf.json
index f5d9aa4..aa5e4df 100644
--- a/app/src-tauri/tauri.conf.json
+++ b/app/src-tauri/tauri.conf.json
@@ -1,7 +1,7 @@
{
"$schema": "https://schema.tauri.app/config/2",
"productName": "MDFlux",
- "version": "0.3.0",
+ "version": "0.3.1",
"identifier": "com.projektvisyo.mdflux",
"build": {
"beforeDevCommand": "npm run dev",
diff --git a/docs/cross-platform/releases-and-verification.md b/docs/cross-platform/releases-and-verification.md
index 072e7cf..d8b66a8 100644
--- a/docs/cross-platform/releases-and-verification.md
+++ b/docs/cross-platform/releases-and-verification.md
@@ -94,6 +94,41 @@ Optional flags:
- `--json-out report.json`: machine-readable JSON report
- `--fixtures-dir tests/release-fixtures/samples`: conversion sample fixtures
- `--keep-temp`: retain the extraction directory for debugging
+- `--app-smoke`: launch the extracted executable in isolated package-verification mode,
+ repeat against the same test data to exercise restart behavior, then copy and launch the
+ payload from a relocated directory to confirm resource lookup follows the executable.
+
+Release and release-candidate CI enable `--app-smoke` for all four platform/edition archives.
+Linux jobs install `xvfb` and invoke the verifier under `xvfb-run -a` so the packaged app can
+initialize its Tauri runtime and event loop in a headless runner. Package-verification mode
+clears the configured windows, so it does not initialize a webview. This smoke gate checks
+startup, runtime provisioning, conversion, restart state, and resource relocation; it does
+**not** test visible GUI behavior or human interaction.
+
+The executable's `--verify-package ABSOLUTE_TEST_DIRECTORY` mode uses only that directory for
+verification data and application data. It creates a `.mdflux-verification` marker and writes
+`report.json`; an existing directory is accepted only when the marker is present. The Python
+standalone runner uses fresh directories beneath a new `--work-dir` and preserves that work
+directory and reports for inspection. When `--app-smoke` is run through `tools.release`, the
+enclosing verifier removes its temporary directory at completion unless `--keep-temp` is set.
+Choose an absolute work path outside the extracted payload; existing work directories are
+refused and never removed.
+
+The Lite smoke verifies that the versioned `app-data/bin/uv-0.12.3/uv[.exe]` exists and that
+the first two output tokens are exactly `uv 0.12.3` on first launch and restart. To exercise
+replacement of a legacy unversioned
+installer, supply an older uv executable with the packaged-app runner:
+
+```bash
+python tools/release/check_packaged_app.py \
+ --executable /path/to/extracted/MDFlux \
+ --work-dir /absolute/path/to/new-app-smoke \
+ --legacy-uv /path/to/legacy/uv
+```
+
+Use `uv.exe` for the legacy executable on Windows. This regression seeds it into the marked,
+isolated app-data directory before the first launch, then checks that Lite installs and uses the
+versioned uv path. It never uses the developer's normal application data.
The verifier checks layout, `resources/edition.json`, dependency lock checksum, bundled Python
(Full), core/OCR/audio imports (Full), sidecar health, sample conversions, real image and
@@ -103,6 +138,24 @@ the same two OCR paths, protecting Lite's optional OCR installation.
> Use the verifier version available in your checkout for CI and local checks.
+## Release procedure
+
+Archives reach GitHub only through the Release workflow. v0.3.0 was published from a local build
+after the workflow failed at "Build Windows Lite", which meant the archives users downloaded had
+never passed the gate written for them. The rule from v0.3.1 on:
+
+1. Open the PR and apply the `integration` label (or dispatch "Release candidate" with the exact
+ commit SHA). All four RC archives must verify, including `--app-smoke`.
+2. Run the manual clean-machine checks on the RC archives: Lite first-run provisioning on a host
+ with no uv cache (`%LOCALAPPDATA%\uv` on Windows), Linux Lite extracted outside any `target/`
+ directory, a scanned-PDF OCR conversion on Full, and an AI cleanup "Test" against one hosted
+ provider. Record pass/fail with evidence before tagging.
+3. Merge, then push the `vX.Y.Z` tag that matches `app/src-tauri/tauri.conf.json`.
+4. Wait for the Release workflow. If any job fails, fix the cause and re-run the workflow for the
+ same tag with `workflow_dispatch`. Never build locally and upload by hand.
+5. Publish the draft the workflow created as a **pre-release**. Point open issue reporters at it.
+6. Promote to a full release after reporters confirm, or after seven days without a regression.
+
## Portable archive layout inside `edition.json`
Every archive includes `resources/edition.json` (schema version 1) with `edition`, `platform`,
@@ -121,6 +174,7 @@ Every archive includes `resources/edition.json` (schema version 1) with `edition
| Sample conversions | Yes | Yes |
| Image and scanned-PDF OCR | Locked-runtime CI | Yes |
| No runtime provisioning into app data | N/A | Yes |
+| Packaged launch, restart, and relocation (`--app-smoke`) | Release CI | Release CI |
**Pending:** end-to-end verification reports for all four archives on clean Windows and Ubuntu
hosts.
diff --git a/tests/release-fixtures/test_verifier.py b/tests/release-fixtures/test_verifier.py
index ba26556..c8cc95c 100644
--- a/tests/release-fixtures/test_verifier.py
+++ b/tests/release-fixtures/test_verifier.py
@@ -149,6 +149,44 @@ class ArchiveBuilderTests(unittest.TestCase):
class StructuralVerificationTests(ArchiveBuilderTests):
+ def test_app_smoke_receives_extracted_executable_and_sibling_workdir(self) -> None:
+ with patch("tools.release.verify.run_packaged_app_smoke") as smoke:
+ report = verify_archive(
+ self.lite_windows,
+ platform="windows-x64",
+ edition="lite",
+ fixtures_dir=SAMPLES_DIR,
+ app_smoke=True,
+ )
+
+ check = next(item for item in report.checks if item.name == "packaged-app-smoke")
+ self.assertTrue(check.passed)
+ smoke.assert_called_once()
+ executable, work_dir = smoke.call_args.args
+ self.assertEqual(executable.name, "MDFlux.exe")
+ self.assertEqual(executable.parent.name, "extract")
+ self.assertEqual(work_dir.name, "app-smoke")
+ self.assertEqual(work_dir.parent, executable.parent.parent)
+
+ def test_app_smoke_exception_fails_verification_report(self) -> None:
+ with patch(
+ "tools.release.verify.run_packaged_app_smoke",
+ side_effect=RuntimeError("smoke fixture failed"),
+ ) as smoke:
+ report = verify_archive(
+ self.lite_windows,
+ platform="windows-x64",
+ edition="lite",
+ fixtures_dir=SAMPLES_DIR,
+ app_smoke=True,
+ )
+
+ check = next(item for item in report.checks if item.name == "packaged-app-smoke")
+ self.assertFalse(check.passed)
+ self.assertIn("smoke fixture failed", check.detail)
+ self.assertFalse(report.passed)
+ smoke.assert_called_once()
+
def test_lite_windows_passes_layout(self) -> None:
report = verify_archive(
self.lite_windows,
diff --git a/tests/test_check_packaged_app.py b/tests/test_check_packaged_app.py
new file mode 100644
index 0000000..88baf84
--- /dev/null
+++ b/tests/test_check_packaged_app.py
@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "tools" / "release"))
+import check_packaged_app as checker
+
+
+class PackagedAppReportTests(unittest.TestCase):
+ def test_accepts_passed_report_with_expected_root(self) -> None:
+ with tempfile.TemporaryDirectory() as temp:
+ root = Path(temp) / "payload"
+ report_path = Path(temp) / "report.json"
+ report_path.write_text(
+ json.dumps({"passed": True, "resource_root": str(root)}), encoding="utf-8"
+ )
+ self.assertTrue(checker.validate_report(report_path, root)["passed"])
+
+ def test_rejects_failed_report(self) -> None:
+ with tempfile.TemporaryDirectory() as temp:
+ report_path = Path(temp) / "report.json"
+ report_path.write_text(
+ json.dumps({"passed": False, "error": "fixture failed"}), encoding="utf-8"
+ )
+ with self.assertRaisesRegex(checker.VerificationError, "fixture failed"):
+ checker.validate_report(report_path, Path(temp))
+
+ def test_rejects_resource_root_mismatch(self) -> None:
+ with tempfile.TemporaryDirectory() as temp:
+ report_path = Path(temp) / "report.json"
+ report_path.write_text(
+ json.dumps({"passed": True, "resource_root": str(Path(temp) / "wrong")}),
+ encoding="utf-8",
+ )
+ with self.assertRaisesRegex(checker.VerificationError, "resource_root mismatch"):
+ checker.validate_report(report_path, Path(temp) / "expected")
+
+ def test_lite_uv_version_requires_exact_first_two_tokens(self) -> None:
+ with tempfile.TemporaryDirectory() as temp:
+ test_dir = Path(temp)
+ executable = test_dir / "MDFlux"
+ executable.touch()
+ uv_name = "uv.exe" if checker.os.name == "nt" else "uv"
+ uv = test_dir / "app-data" / "bin" / "uv-0.12.3" / uv_name
+ uv.parent.mkdir(parents=True)
+ uv.touch()
+ with patch(
+ "check_packaged_app.subprocess.run",
+ return_value=SimpleNamespace(returncode=0, stdout="uv 0.12.3", stderr=""),
+ ):
+ checker.verify_lite_uv(test_dir, executable)
+ with patch(
+ "check_packaged_app.subprocess.run",
+ return_value=SimpleNamespace(returncode=0, stdout="not-uv 0.12.3", stderr=""),
+ ):
+ with self.assertRaisesRegex(checker.VerificationError, "does not report"):
+ checker.verify_lite_uv(test_dir, executable)
+
+ def test_subprocess_failure_rejects_and_removes_stale_report(self) -> None:
+ with tempfile.TemporaryDirectory() as temp:
+ root = Path(temp)
+ executable = root / "MDFlux"
+ executable.touch()
+ test_dir = root / "test-data"
+ test_dir.mkdir()
+ stale_report = test_dir / "report.json"
+ stale_report.write_text(
+ json.dumps({"passed": True, "resource_root": str(executable.parent)}),
+ encoding="utf-8",
+ )
+ with patch(
+ "check_packaged_app.subprocess.run",
+ return_value=SimpleNamespace(returncode=1, stdout="", stderr="launch failed"),
+ ):
+ with self.assertRaisesRegex(checker.VerificationError, "exited 1"):
+ checker.run_verification(executable, test_dir, root)
+ self.assertFalse(stale_report.exists())
+
+ def test_success_exit_without_fresh_report_rejects_stale_result(self) -> None:
+ with tempfile.TemporaryDirectory() as temp:
+ root = Path(temp)
+ executable = root / "MDFlux"
+ executable.touch()
+ test_dir = root / "test-data"
+ test_dir.mkdir()
+ stale_report = test_dir / "report.json"
+ stale_report.write_text(
+ json.dumps({"passed": True, "resource_root": str(executable.parent)}),
+ encoding="utf-8",
+ )
+ with patch(
+ "check_packaged_app.subprocess.run",
+ return_value=SimpleNamespace(returncode=0, stdout="", stderr=""),
+ ):
+ with self.assertRaisesRegex(checker.VerificationError, "Cannot read verification report"):
+ checker.run_verification(executable, test_dir, root)
+ self.assertFalse(stale_report.exists())
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_check_workflow_tools.py b/tests/test_check_workflow_tools.py
new file mode 100644
index 0000000..b648631
--- /dev/null
+++ b/tests/test_check_workflow_tools.py
@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import sys
+import unittest
+from pathlib import Path
+
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "tools" / "release"))
+import check_workflow_tools as checker
+
+
+class WorkflowUvVersionTests(unittest.TestCase):
+ def test_reads_platform_version_constant(self) -> None:
+ source = 'pub const UV_VERSION: &str = "0.12.3";'
+ self.assertEqual(checker.pinned_uv_version(source), "0.12.3")
+
+ def test_accepts_matching_setup_uv_version(self) -> None:
+ text = """jobs:
+ build:
+ steps:
+ - uses: astral-sh/setup-uv@deadbeef
+ with:
+ version: "0.12.3"
+ enable-cache: true
+ - run: uv --version
+"""
+ self.assertEqual(checker.workflow_errors(Path("ci.yml"), text, "0.12.3"), [])
+
+ def test_rejects_missing_or_mismatched_setup_uv_version(self) -> None:
+ for setup in (
+ " - uses: astral-sh/setup-uv@deadbeef\n",
+ ' - uses: astral-sh/setup-uv@deadbeef\n with:\n version: "0.5.11"\n',
+ ):
+ with self.subTest(setup=setup):
+ errors = checker.workflow_errors(Path("ci.yml"), setup, "0.12.3")
+ self.assertEqual(len(errors), 1)
+ self.assertIn("does not match platform UV_VERSION", errors[0])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tools/release/check_packaged_app.py b/tools/release/check_packaged_app.py
new file mode 100644
index 0000000..ea13173
--- /dev/null
+++ b/tools/release/check_packaged_app.py
@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+UV_VERSION = "0.12.3"
+VERIFICATION_MARKER = ".mdflux-verification"
+TIMEOUT_SECONDS = 600
+
+
+class VerificationError(RuntimeError):
+ pass
+
+
+def canonical_path(path: str | Path) -> str:
+ value = os.path.normpath(str(Path(path).resolve()))
+ if os.name == "nt":
+ if value.startswith("\\\\?\\UNC\\"):
+ value = "\\\\" + value[8:]
+ elif value.startswith("\\\\?\\"):
+ value = value[4:]
+ value = os.path.normcase(value)
+ return value
+
+
+def validate_report(report_path: Path, expected_root: Path) -> dict[str, Any]:
+ try:
+ report = json.loads(report_path.read_text(encoding="utf-8"))
+ except (OSError, json.JSONDecodeError) as error:
+ raise VerificationError(f"Cannot read verification report {report_path}: {error}") from error
+ if not isinstance(report, dict) or report.get("passed") is not True:
+ detail = report.get("error", "report did not pass") if isinstance(report, dict) else "invalid report"
+ raise VerificationError(f"Packaged verification failed: {detail}")
+ actual_root = report.get("resource_root")
+ if not isinstance(actual_root, str) or canonical_path(actual_root) != canonical_path(expected_root):
+ raise VerificationError(
+ f"Packaged resource_root mismatch: expected {expected_root}, got {actual_root!r}"
+ )
+ return report
+
+
+def run_verification(executable: Path, test_dir: Path, cwd: Path) -> dict[str, Any]:
+ test_dir.mkdir(parents=True, exist_ok=True)
+ (test_dir / VERIFICATION_MARKER).write_text(
+ "MDFlux isolated package verification\n", encoding="utf-8"
+ )
+ report_path = test_dir / "report.json"
+ report_path.unlink(missing_ok=True)
+ try:
+ env = os.environ.copy()
+ env["UV_NO_CACHE"] = "1"
+ result = subprocess.run(
+ [str(executable), "--verify-package", str(test_dir)],
+ cwd=cwd,
+ capture_output=True,
+ text=True,
+ timeout=TIMEOUT_SECONDS,
+ check=False,
+ env=env,
+ **(
+ {"creationflags": subprocess.CREATE_NO_WINDOW}
+ if os.name == "nt"
+ else {}
+ ),
+ )
+ except subprocess.TimeoutExpired as error:
+ raise VerificationError(f"Packaged verification timed out after {TIMEOUT_SECONDS}s") from error
+ if result.returncode != 0:
+ output = (result.stderr or result.stdout).strip()
+ raise VerificationError(
+ f"Packaged executable exited {result.returncode}: {output or 'no diagnostic output'}"
+ )
+ return validate_report(report_path, executable.parent)
+
+
+def verify_lite_uv(test_dir: Path, executable: Path) -> None:
+ if os.name == "nt":
+ uv_name = "uv.exe"
+ else:
+ uv_name = "uv"
+ installed_uv = test_dir / "app-data" / "bin" / f"uv-{UV_VERSION}" / uv_name
+ if not installed_uv.is_file():
+ raise VerificationError(f"Versioned Lite uv was not installed: {installed_uv}")
+ try:
+ result = subprocess.run(
+ [str(installed_uv), "--version"],
+ cwd=executable.parent,
+ capture_output=True,
+ text=True,
+ timeout=30,
+ check=False,
+ )
+ except (OSError, subprocess.TimeoutExpired) as error:
+ raise VerificationError(f"Cannot query installed uv at {installed_uv}: {error}") from error
+ version_tokens = (result.stdout + result.stderr).strip().split()
+ if result.returncode != 0 or version_tokens[:2] != ["uv", UV_VERSION]:
+ raise VerificationError(
+ f"Installed uv does not report {UV_VERSION}: {(result.stdout + result.stderr).strip()}"
+ )
+
+
+def seed_legacy_uv(source: Path, test_dir: Path) -> None:
+ test_dir.mkdir(parents=True, exist_ok=True)
+ (test_dir / VERIFICATION_MARKER).write_text(
+ "MDFlux isolated package verification\n", encoding="utf-8"
+ )
+ destination = test_dir / "app-data" / "bin" / ("uv.exe" if os.name == "nt" else "uv")
+ destination.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copy2(source, destination)
+ if os.name != "nt":
+ destination.chmod(destination.stat().st_mode | 0o111)
+
+
+def run(executable: Path, work_dir: Path, legacy_uv: Path | None = None) -> None:
+ if not work_dir.is_absolute():
+ raise VerificationError("--work-dir must be an absolute path")
+ executable = executable.resolve(strict=True)
+ work_dir = work_dir.resolve(strict=False)
+ if not executable.is_file():
+ raise VerificationError(f"Executable is not a file: {executable}")
+ if work_dir.exists():
+ raise VerificationError(f"Refusing to use existing work directory: {work_dir}")
+ source_payload = executable.parent
+ try:
+ work_dir.relative_to(source_payload)
+ except ValueError:
+ pass
+ else:
+ raise VerificationError("Work directory cannot be inside the source payload")
+ if legacy_uv is not None:
+ legacy_uv = legacy_uv.resolve(strict=True)
+ if not legacy_uv.is_file():
+ raise VerificationError(f"Legacy uv is not a file: {legacy_uv}")
+
+ work_dir.mkdir(parents=True)
+ first = work_dir / "first-run"
+ if legacy_uv is not None:
+ seed_legacy_uv(legacy_uv, first)
+ report = run_verification(executable, first, work_dir)
+ if report.get("edition", "").lower() == "lite":
+ verify_lite_uv(first, executable)
+ elif legacy_uv is not None:
+ raise VerificationError("--legacy-uv requires a Lite package")
+
+ # A second launch against the same marked directory exercises persisted state.
+ restarted = run_verification(executable, first, work_dir)
+ if restarted.get("edition", "").lower() == "lite":
+ verify_lite_uv(first, executable)
+ elif legacy_uv is not None:
+ raise VerificationError("--legacy-uv requires a Lite package")
+
+ relocated = work_dir / "relocated-payload"
+ shutil.copytree(source_payload, relocated)
+ relocated_executable = relocated / executable.name
+ relocated_test_dir = work_dir / "relocated-run"
+ moved_report = run_verification(relocated_executable, relocated_test_dir, work_dir)
+ if canonical_path(moved_report["resource_root"]) != canonical_path(relocated):
+ raise VerificationError("Relocated executable did not resolve resources from moved payload")
+ print("Packaged app verification: first run, restart, and relocation passed")
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description="Verify an extracted MDFlux app payload.")
+ parser.add_argument("--executable", required=True, type=Path)
+ parser.add_argument("--work-dir", required=True, type=Path)
+ parser.add_argument("--legacy-uv", type=Path)
+ args = parser.parse_args(argv)
+ try:
+ run(args.executable, args.work_dir, args.legacy_uv)
+ except (OSError, VerificationError, shutil.Error) as error:
+ print(f"Packaged app verification failed: {error}", file=sys.stderr)
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/tools/release/check_workflow_tools.py b/tools/release/check_workflow_tools.py
index 660ad2c..10a7519 100644
--- a/tools/release/check_workflow_tools.py
+++ b/tools/release/check_workflow_tools.py
@@ -6,15 +6,47 @@ from pathlib import Path
WORKFLOWS = (
+ Path(".github/workflows/ci.yml"),
Path(".github/workflows/release-candidate.yml"),
Path(".github/workflows/release.yml"),
)
+PLATFORM_MODULE = Path("app/src-tauri/src/platform/mod.rs")
JOB_HEADER = re.compile(r"^ ([a-zA-Z0-9_-]+):\s*$", re.MULTILINE)
UV_COMMAND = re.compile(
r"^\s+(?:uv(?:\.exe)?|&\s+uv(?:\.exe)?|python(?:\.exe)?\s+-m\s+uv)\s+",
re.IGNORECASE | re.MULTILINE,
)
UV_SETUP = "uses: astral-sh/setup-uv@"
+UV_VERSION = re.compile(r'^pub const UV_VERSION: &str = "([^\"]+)";', re.MULTILINE)
+SETUP_STEP = re.compile(
+ r"^\s*- uses: astral-sh/setup-uv@[^\r\n]*\r?\n(?P<body>(?:(?!^\s*- ).*(?:\r?\n|$))*)",
+ re.MULTILINE,
+)
+STEP_VERSION = re.compile(r'^\s+version:\s*["\']?([^\s"\']+)', re.MULTILINE)
+
+
+def pinned_uv_version(platform_source: str) -> str | None:
+ match = UV_VERSION.search(platform_source)
+ return match.group(1) if match else None
+
+
+def workflow_errors(workflow: Path, text: str, expected_version: str) -> list[str]:
+ errors: list[str] = []
+ for job, block in job_blocks(text):
+ command = UV_COMMAND.search(block)
+ setup = block.find(UV_SETUP)
+ if command and (setup < 0 or setup > command.start()):
+ errors.append(f"{workflow}: job {job!r} runs uv before pinned setup-uv")
+
+ for match in SETUP_STEP.finditer(text):
+ version = STEP_VERSION.search(match.group("body"))
+ actual_version = version.group(1) if version else None
+ if actual_version != expected_version:
+ errors.append(
+ f"{workflow}: setup-uv version {actual_version!r} does not match "
+ f"platform UV_VERSION {expected_version!r}"
+ )
+ return errors
def job_blocks(text: str) -> list[tuple[str, str]]:
@@ -28,15 +60,14 @@ def job_blocks(text: str) -> list[tuple[str, str]]:
def main() -> int:
errors: list[str] = []
+ platform_source = PLATFORM_MODULE.read_text(encoding="utf-8")
+ expected_version = pinned_uv_version(platform_source)
+ if expected_version is None:
+ print(f"{PLATFORM_MODULE}: missing UV_VERSION constant", file=sys.stderr)
+ return 1
for workflow in WORKFLOWS:
text = workflow.read_text(encoding="utf-8")
- for job, block in job_blocks(text):
- command = UV_COMMAND.search(block)
- setup = block.find(UV_SETUP)
- if command and (setup < 0 or setup > command.start()):
- errors.append(
- f"{workflow}: job {job!r} runs uv before pinned setup-uv"
- )
+ errors.extend(workflow_errors(workflow, text, expected_version))
if errors:
print("\n".join(errors), file=sys.stderr)
diff --git a/tools/release/verify.py b/tools/release/verify.py
index a665362..003fed0 100644
--- a/tools/release/verify.py
+++ b/tools/release/verify.py
@@ -7,6 +7,7 @@ import tempfile
from pathlib import Path
from .checksum import verify_dependency_lock_checksum
+from .check_packaged_app import run as run_packaged_app_smoke
from .cleanup import safe_remove_tree
from .extract import extract_archive
from .layout import validate_layout
@@ -40,6 +41,7 @@ def verify_archive(
edition: str,
fixtures_dir: Path | None = None,
keep_temp: bool = False,
+ app_smoke: bool = False,
) -> VerificationReport:
archive_path = resolve(archive)
fixtures = fixtures_dir or _default_fixtures_dir()
@@ -81,6 +83,18 @@ def verify_archive(
for check in validate_layout(extract_dir, platform=platform, edition=edition):
report.add(check)
+ if app_smoke:
+ from .layout import executable_name
+
+ try:
+ run_packaged_app_smoke(
+ extract_dir / executable_name(platform),
+ temp_root / "app-smoke",
+ )
+ report.add(CheckResult("packaged-app-smoke", True, "Launch, restart, and relocation passed"))
+ except Exception as exc:
+ report.add(CheckResult("packaged-app-smoke", False, str(exc)))
+
edition_json = extract_dir / "resources" / "edition.json"
manifest = None
if edition_json.is_file():
@@ -205,6 +219,11 @@ def build_parser() -> argparse.ArgumentParser:
action="store_true",
help="Keep the extracted archive directory for debugging",
)
+ parser.add_argument(
+ "--app-smoke",
+ action="store_true",
+ help="Launch the packaged app, repeat verification, and check relocation",
+ )
return parser
@@ -217,6 +236,7 @@ def main(argv: list[str] | None = None) -> int:
edition=args.edition,
fixtures_dir=Path(args.fixtures_dir),
keep_temp=args.keep_temp,
+ app_smoke=args.app_smoke,
)
human = format_human_report(report)
print(human)