# The window, on Windows and Linux A Tauri shell over the same local server the macOS app talks to. It draws nothing. ```bash cd desktop npm install npm run dev ``` Needs a Rust toolchain — `brew install rustup && rustup toolchain install stable`, or your platform's equivalent. `npm run test:all` at the repository root runs the Rust tests along with everything else, and says plainly when it could not. ## What this is The macOS app was never self-contained: it spawns `bin/seo-audit.mjs` with `--serve 0`, reads the port off stdout, and talks to it over HTTP. This does exactly the same thing and points a webview at the result, so Windows and Linux get the report the browser already renders — sidebar, score ring and all — inside a real window. ``` Tauri window → 127.0.0.1:PORT → node --serve 0 → src/*.mjs this file loopback the sidecar the checks ``` Only the first box is new. `src/main.rs` is a port of `mac/SeoAudit/Engine.swift`, including the parts that were only learned by getting them wrong there: - **Port zero.** The operating system picks a free one and the server prints where it landed. Guessing is how two copies of an app fight over one port. - **Node by path, not by `PATH`.** A window launched from a dock or a Start menu inherits almost none, so looking Node up the obvious way finds nothing on a machine that plainly has it. - **The child dies with the window, however the window dies.** A server that outlives the window that opened it holds its port against the next launch — a bug that shipped once on macOS. Closing fires `Destroyed` and quitting fires `Exit`, and both stop it; nothing fires when a process is terminated outright, and on Windows the engine then survived. A job object with `KILL_ON_JOB_CLOSE` moves that promise from this code to the kernel. CI kills the app the hard way on both platforms to check. - **A failure is a window, not a stream.** An app that opens and does nothing is the worst version of this, and it is the one that shipped on macOS. ## Why the identifier is not the app's `com.nurkamol.seo-audit.desktop`, where the macOS app is `com.nurkamol.seo-audit`. They are two programs, and on macOS one identifier is one `defaults` domain — sharing it would have this shell reading and writing the app's settings, its update-check timestamps and its dismissed-version list. Launch Services would also have two apps claiming to be the same one. macOS is deliberately not in `bundle.targets`: the Swift app is the macOS release and is better there. If a macOS build of this ever ships alongside it, it needs a distinct **name** too — both would want `/Applications/SEO Audit.app`. They do share one thing on purpose: the reports folder. A crawl run in either window appears in the other's sidebar, because there is one library rather than two copies of one. ## What it must never grow A control. Anything this is tempted to draw itself would exist on Windows and not on macOS, and the rule that keeps five front ends honest is that none of them re-implements anything. New UI belongs in the served HTML, where every platform gets it at once. ## The window's furniture A menu of **File · Edit · Help**, and every item in it is either navigation or a link. Edit is the predefined one rather than hand-written, because on Linux and Windows a webview with no Edit menu is a text field where Ctrl-C does nothing — which is not a thing anybody would think to test. **External links leave.** A report is full of the audited site's own URLs, and following one used to replace the report with somebody else's website, inside a window with no address bar to get out of and holding this app's capabilities. Now the engine's own origin is the app and everything else opens in a browser. `is_the_app()` is the whole policy and it is the most-tested function here. **Saving is not a control this owns.** The seven export formats are links in the served HTML — `/reports//export?as=…` — so a plain browser downloads them and this window inherits the lot without a native dialog or a menu item. That is the rule working: the feature landed once and every platform got it. ## Packaging ```bash npm run stage # stage a Node and the engine, and prove the staged copy runs npm run build # bundle for this platform ``` Named `stage` rather than `prepare`, because npm runs a script called `prepare` on every `npm install` — which would copy 110 MB and shell out to `rustc` before anything had asked it to, including during `npm ci` in CI where the toolchain may not be on the path yet. `scripts/prepare.mjs` copies `process.execPath` to `src-tauri/binaries/node-` — the name Tauri looks for, asked of `rustc` rather than worked out, because a name one character off does not fail loudly, it bundles nothing. The engine itself goes to `src-tauri/engine/`. Then it **starts the staged copy and waits for it to announce a port.** The first bundle staged `bin` and `src` and not `worker`, which `--serve` imports, so it built, installed, launched, spawned its engine and waited fifteen seconds for an address that was never coming. A list of directories is exactly the kind of thing that looks right and is not. What comes out: | | | |---|---| | `SEO Audit_1.34.0_x64-setup.exe` | **23 MB** — NSIS compresses the runtime hard | | `SEO Audit_1.34.0_amd64.deb` | **45 MB** | | `SEO Audit_1.34.0_amd64.AppImage` | **115 MB** — uncompressed, which is what a single file costs | Inside a macOS build, for reference — the layout is the same everywhere and this is the one that can be inspected on a Mac: ``` 115 MB SEO Audit.app ├─ Contents/MacOS/node 110 MB the sidecar, triple stripped by Tauri ├─ Contents/MacOS/seo-audit 3 MB this shell └─ Contents/Resources/engine 0.5 MB bin, src, worker, package.json ``` macOS is not in `bundle.targets`; that build is only for checking the mechanism on the machine most likely to be doing the checking — which is how the missing `worker/` was found. **What has not been proven:** the Windows and Linux bundles build and their contents are the right size, and nobody has run one. Neither has the upgrade path, which is where the sidecar-staleness bug lives. ### The version check Tauri's NSIS installer has [a reported bug](https://github.com/tauri-apps/tauri/issues/15134) where a Windows upgrade replaces the main binary and leaves the sidecar behind. Here the sidecar *is* the engine, so the app would come back looking new and run the old checks, with nothing on screen to say so — a missing finding reads exactly like a passing one, and a stale engine is a whole report of them. So a bundled build asks the engine `--version` before starting it, and refuses with an explanation if it disagrees with the shell's. Development is exempt: the checkout is the engine, and whatever the working tree says is what was meant. ## Updates The macOS app settled the principle: **the thing that installed it is the thing that replaces it.** That generalises, but not evenly — the platforms differ in what they let a program do without a password it has no way to ask for. So there is no single Update button that always works. The shell works out how this copy got here and offers the one action that is correct for it: | Installed by | What it offers | |---|---| | winget | Runs `winget upgrade` here, then offers to relaunch. A per-user install needs no elevation, which is the same property that makes Homebrew work on macOS | | apt | Shows the command. `apt` needs root, and a GUI app that shells out to `sudo` is one that hangs on a password prompt nobody can see | | AppImage · the installer · by hand | Opens the release page | It deliberately does not download a binary and put it in place itself. Doing that safely needs a signature to check or a checksum to compare, and an updater that overwrites an application on the strength of a plain HTTPS response is a supply-chain hole with a progress bar on it. The check is once a day, on a thread, after the window is up — an update is never worth delaying a report for. **Check for Updates…** in the app menu asks regardless. It asks GitHub's API and falls back to the Atom feed, because the anonymous API allows sixty calls an hour **per address**, shared with every other tool on the machine, and being refused is ordinary. The feed cannot tell a prerelease from a release, so a version learned there is announced with that said out loud rather than asserted — the same wording the macOS app uses, for the same reason. No HTTP client crate: the Node this app already ships has `fetch`, and adding a TLS stack so a 110 MB bundle can make one request a year is the larger thing, not the smaller one. ## Proving a bundle came from here Every bundle a tagged build attaches carries a signed [build provenance][ab] attestation: which workflow made it, from which commit, on which runner. The `Attest what was built` step in `.github/workflows/desktop.yml` writes it before the upload, so an attested file that failed to attach is a re-run rather than an attached file nobody can check. ```bash gh attestation verify SEO.Audit_1.40.1_x64-setup.exe --repo nurkamol/seo-audit ``` That works on a downloaded installer, needs no trust in this README, and fails for a bundle built anywhere else. It exists because a winget moderator could not tie the 1.38.1 installer to the source at its tag and was right — it had been uploaded hours after the tagged build rather than by it. A timeline in a comment is an argument; this is an answer. Release builds only. Nothing downstream can verify a bundle that was never published, and the attestation is bound to the run that produced the file. [ab]: https://docs.github.com/en/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds ## Bootstrapping winget Every release after the first is automatic: the `winget` job in `.github/workflows/desktop.yml` submits the new version with [winget-releaser][wr]. That action only ever **updates** a package, though — it exits with *"Package Nurkamol.SeoAudit does not exist in the winget-pkgs repository"* until one version is already there. So the first one goes by hand, once, and never again. It needs a classic GitHub token with the `public_repo` scope — the same one the `WINGET_TOKEN` secret holds. It has to fork `microsoft/winget-pkgs` into your account and open a pull request from it. ```bash brew install komac # cross-platform; wingetcreate is Windows-only GITHUB_TOKEN= komac new Nurkamol.SeoAudit \ --version 1.40.1 \ --urls https://github.com/nurkamol/seo-audit/releases/download/v1.40.1/SEO.Audit_1.40.1_x64-setup.exe \ --publisher "Nurkamol Vakhidov" \ --publisher-url https://github.com/nurkamol \ --package-name "SEO Audit" \ --package-url https://github.com/nurkamol/seo-audit \ --license MIT \ --license-url https://github.com/nurkamol/seo-audit/blob/main/LICENSE \ --moniker seo-audit \ --short-description "Crawl a site's sitemap and check every page" \ --description "Audits every page a sitemap lists rather than only the homepage, and groups what it finds by the thing that has to change. Reports the checks that passed and the ones that did not apply, so a missing finding cannot be mistaken for a passing one. The crawl runs on your machine: it fetches the site you point it at, and your audit results are never sent to the publisher. Features you turn on yourself contact Google PageSpeed Insights and Search Console, and the app checks GitHub for new versions." \ --submit ``` **Use the manifest schema version winget currently accepts.** The repository deprecates older ones and a bot rejects the submission when it meets one — 1.41.0 went in as `1.12.0`, copied from the 1.38.1 manifests, and was told to move to `1.28.0` five weeks later. The version is in `ManifestVersion` and in the `$schema` comment of all three files, and the field names have not changed between them. The current one is whatever a freshly merged manifest in `microsoft/winget-pkgs` carries; komac emits it for itself, so this only bites a hand-written submission. **komac needs a real terminal.** It reads the NSIS script and stops on any aborting entry it finds — ours says *"Failed to install WebView2!"*, which is the installer's own error path and not a problem — then asks whether to carry on. With no TTY it fails with *"The input device is not a TTY"*, and `--dry-run` stops in the same place. Run it yourself, or do what 1.41.0 did: take the manifests from the last submitted version, change the version, installer URL, SHA256, release date, release notes URL and description, and push them to a branch on your `winget-pkgs` fork through the API. Three files, and the SHA256 is on the release in `SHA256SUMS.txt`. Quote the description if it contains a colon, or the YAML will not parse. Drop `--submit` to see the manifests without opening anything. Use the newest release's version and installer URL rather than the ones above if time has passed — the URL is on the release page, and `SHA256SUMS.txt` beside it is the hash komac will compute for itself. **Submit a version whose installer the tagged build attached**, and never re-upload an installer to a release that is already out. The first attempt was 1.38.1, whose `-setup.exe` was uploaded six hours after the rest of that release — a separate run — and a moderator refused it as untraceable to the source at the tag. `gh release view v --json assets` prints each asset's `createdAt`: the Windows bundle should sit within a minute or two of the Linux ones. **The description is a claim somebody checks.** The first submission said "Nothing leaves the machine" and the moderator asked what the update check was doing, which was fair — the shell asks api.github.com for new versions, and PageSpeed Insights and Search Console are opt-in calls to Google. What is true is that results are never sent to the publisher, so that is what it says now. `winget-releaser` carries the locale manifest forward on every later release, so wording fixed here is wording fixed once. A maintainer reviews the pull request. The first one, 1.41.0, was opened on 26 September 2026 and merged on 20 November, with no blockers and one optional note: the installer carries no Authenticode signature, and signing it would speed review. Unsigned is allowed and is not on its own a reason for refusal. **Until a version has merged, no Windows copy is a winget install**, so `winget upgrade` has nothing to move and the shell sends those copies to the release page. That is the correct behaviour, not a fallback — see [Updates](#updates). ## Versions tagged while winget was not ready The `winget` job exits cleanly when the package is not in `microsoft/winget-pkgs` yet, so a release tagged before the first submission merged was never sent. 1.42.0 and 1.42.1 were. To send one now, re-run **only that run's `winget` job**: ```bash gh run list -w "Desktop shell" --json databaseId,headBranch # the tag's run gh run view --json jobs --jq '.jobs[] | "\(.databaseId) \(.name)"' gh run rerun --job ``` Never a `workflow_dispatch` with `tag` for this: that rebuilds the bundles and uploads the installer again, which is exactly the provenance problem that got 1.38.1 refused. Re-running the one job reuses what the tag build attached. ## Keep the fork synced winget-releaser starts by syncing your `winget-pkgs` fork with `microsoft/winget-pkgs`. When upstream has added or changed a workflow file since the last sync, GitHub refuses that from a token without the `workflow` scope, and `WINGET_TOKEN` only has `public_repo`. The job then fails with: ``` while merging 45866 upstream commits from microsoft/winget-pkgs into nurkamol/winget-pkgs Status 422: refusing to allow a Personal Access Token to create or update workflow `.github/workflows/…` without `workflow` scope ``` That is what happened to 1.42.1 on 20 November 2026. Sync the fork with your own login, which has the scope, and re-run the job as above: ```bash gh repo sync nurkamol/winget-pkgs --source microsoft/winget-pkgs --branch master ``` Doing the same before tagging prevents it. Giving `WINGET_TOKEN` the `workflow` scope would also prevent it, but that lets a secret stored in this repository rewrite workflows in every public repository you own, so it is deliberately not done. [wr]: https://github.com/vedantmgoyal9/winget-releaser ## Not done yet All five phases. A version tag builds the three bundles, installs and runs each one on its runner, and attaches them to that release. The winget row of that table is the one thing that is not fully self-serving: each version is a pull request against `microsoft/winget-pkgs` that a moderator has to approve, and the job needs the `WINGET_TOKEN` secret and a synced fork (see above). Without the secret the release still ships a `setup.exe`; it is just not a winget install, so that copy is sent to the release page rather than offered `winget upgrade`. The job warns rather than passing quietly, because a release that did not publish looks exactly like one that did. ## A note on running it `npm run dev` is the supported way. The binary under `target/debug` can be run directly, but in a dev build the Tauri CLI serves `ui/` rather than embedding it, so the fallback page renders blank when the binary is launched on its own. That is a development artifact, not a bug — a release build embeds it.