@sdods/cli 0.2.2 → 0.3.1

package/dist/commands/analyze.d.ts

@@ -6,6 +6,8 @@ export interface InitFromAppOptions {
     slug?: string;
     name?: string;
     openapi?: string;
+    maxFiles?: number;
+    maxDepth?: number;
     force?: boolean;
     importSpecs?: boolean;
     browsers?: string[];

package/dist/commands/analyze.js

@@ -8,7 +8,11 @@ import { projectTemplateFiles } from '../templates/project.js';
 /** Programmatic entry used by `sdods init --from <app>`: analyze → propose → apply. */
 export async function initFromApp(opts) {
     const { analyzeProject, proposeProject, applyProposal } = await import('@sdods/core/analyze');
-    const report = analyzeProject(opts.appPath, { openapi: opts.openapi });
+    const report = analyzeProject(opts.appPath, {
+        openapi: opts.openapi,
+        maxFiles: opts.maxFiles,
+        maxDepth: opts.maxDepth,
+    });
     const proposal = proposeProject(report, {
         slug: opts.slug,
         name: opts.name,
@@ -52,12 +56,18 @@ export function register(program) {
         .option('--force', 'overwrite an existing project when applying')
         .option('--no-import-specs', 'do not copy existing Playwright specs into recorded/imported')
         .option('--report-only', 'print the analysis, skip the proposal')
+        .option('--max-files <n>', 'file budget for the scan (default 25000); raise it on a large monorepo', (v) => Number.parseInt(v, 10))
+        .option('--max-depth <n>', 'directory depth budget for the scan (default 12)', (v) => Number.parseInt(v, 10))
         .action(async (path, opts, cmd) => {
         const ctx = createContext(cmd);
         // the app path is relative to where the command was typed, not to --cwd (the SDODS repo)
         const appPath = resolvePath(process.cwd(), path ?? '.');
         const { analyzeProject, proposeProject, applyProposal } = await import('@sdods/core/analyze');
-        const report = analyzeProject(appPath, { openapi: opts.openapi });
+        const report = analyzeProject(appPath, {
+            openapi: opts.openapi,
+            maxFiles: opts.maxFiles,
+            maxDepth: opts.maxDepth,
+        });
         const slug = opts.project ?? opts.slug;
         const proposal = opts.reportOnly
             ? undefined
@@ -169,41 +179,11 @@ function printReport(r) {
         out(`${icon} ${pc.bold(c.title)} — ${c.detail}${c.fix ? pc.dim(`\n    → ${c.fix}`) : ''}`);
     }
 }
-/**
- * Why each module exists. Modules are inferred by fusing several signals - the file that defines
- * a route, the monorepo workspace, a domain directory, an OpenAPI tag - so the winning signal and
- * its confidence are the part a reviewer actually needs to judge the proposal.
- */
-function printModules(p) {
-    const mods = p.detectedModules ?? [];
-    if (!mods.length)
-        return;
-    out(pc.dim('--- modules ---'));
-    const w = Math.max(6, ...mods.map((m) => m.name.length));
-    for (const m of mods) {
-        const targets = [
-            m.routes ? `${m.routes} route${m.routes === 1 ? '' : 's'}` : '',
-            m.endpoints ? `${m.endpoints} endpoint${m.endpoints === 1 ? '' : 's'}` : '',
-        ]
-            .filter(Boolean)
-            .join(', ');
-        const from = m.evidence[0]?.file;
-        out(`  ${m.name.padEnd(w)}  ${pc.dim(m.confidence.toFixed(2))}  ${targets.padEnd(22)}` +
-            `${pc.dim(m.signals.join('+'))}${from ? pc.dim(`  ← ${from}`) : ''}`);
-    }
-    const ignored = p.ignoredTargets ?? [];
-    if (ignored.length) {
-        out(pc.dim(`--- skipped (${ignored.length}) ---`));
-        for (const i of ignored)
-            out(pc.dim(`  ${i.target.padEnd(20)} ${i.reason}`));
-    }
-}
 function printProposal(p) {
     heading(`Proposed project: ${p.slug}`);
     out(pc.dim(`envs: ${Object.keys(p.envYamls).join(', ')} · starter features: ${Object.keys(p.starterFeatures).length} · coverage targets: ${p.coverageMap.length}`));
     for (const n of p.notes)
         warn(n);
-    printModules(p);
     out(pc.dim('--- sdods.project.yaml ---'));
     const lines = p.projectYaml.split('\n');
     out(lines.slice(0, 60).join('\n'));

package/dist/commands/run.d.ts

@@ -13,6 +13,7 @@ export interface RunFlags {
     retries?: number;
     grep?: string;
     feature?: string;
+    since?: string;
     scenario?: string;
     runId?: string;
     artifactsDir?: string;

package/dist/commands/run.js

@@ -4,6 +4,7 @@ import { execa } from 'execa';
 import pc from 'picocolors';
 import { newRunId, runFiles, } from '@sdods/contracts';
 import { SdodsError, CLI_OVERRIDES_ENV, VERSION, formatFindings, lintProject, listGeneratedProjects, moduleByName, moduleDir, normalizeTagExpr, serializeCliOverrides, } from '@sdods/core';
+import { analyzeChangeImpact } from '@sdods/mcp';
 import { createContext } from '../context.js';
 import { collect, json, out, parseIntFlag, warn } from '../ui.js';
 function addRunOptions(cmd) {
@@ -23,6 +24,7 @@ function addRunOptions(cmd) {
         .option('--retries <n>', 'retries per test', parseIntFlag('retries'))
         .option('--grep <pattern>', 'filter tests by title (regular expression)')
         .option('--feature <path>', 'only this feature file (relative to features/)')
+        .option('--since <range>', 'only features impacted by a git range, e.g. main..HEAD (test-impact analysis)')
         .option('--scenario <name>', 'only scenarios whose title contains this text')
         .option('--run-id <id>', 'run id (default: uuid v7)')
         .option('--artifacts-dir <dir>', 'artifacts root (default: .sdods/runs)')
@@ -249,9 +251,34 @@ export async function runCommand(flags, cmd) {
         const rel = relative(join(cfg.project.root, 'features'), moduleDir(cfg.project.root, moduleByName(projectCfg, m))).replace(/\\/g, '/');
         filters.push(`\\.sdods/generated/${escapeRe(runId)}/${escapeRe(entry.slug)}/[^/]+/${escapeRe(rel)}/`);
     }
+    const featureFilter = (rel) => escapeRe(rel.replace(/^features\//, '').replace(/\.feature$/, '')) + '\\.feature\\.spec';
     if (flags.feature)
-        filters.push(escapeRe(flags.feature.replace(/^features\//, '').replace(/\.feature$/, '')) +
-            '\\.feature\\.spec');
+        filters.push(featureFilter(flags.feature));
+    // --since <range>: run only what the change could have broken.
+    //
+    // `analyzeChangeImpact` has existed for a while and was reachable only
+    // through MCP, so it could advise a human and could not select a run. This is
+    // the seam that was missing; the mapping itself is unchanged.
+    if (flags.since) {
+        const impact = analyzeChangeImpact(cfg.project.root, ctx.rootDir, flags.since);
+        if (impact.impacted.length === 0) {
+            // Deliberately NOT "run everything" and deliberately not a silent empty
+            // run. A run that registered zero scenarios exits 0 and looks identical
+            // to a green run, which is the single most dangerous outcome a test
+            // runner has. Say so, in words, and stop.
+            out(pc.bold(`No features impacted by ${flags.since}.`));
+            out(`  ${impact.changedFiles.length} changed file(s), none reaching a feature.`);
+            out(pc.dim('  Nothing was run. This is not a pass — re-run without --since to verify.'));
+            // Exit 0: selecting nothing is a correct outcome for this flag, not a
+            // failure. The wording above is what stops it being read as a pass.
+            return 0;
+        }
+        out(pc.bold(`--since ${flags.since}: ${impact.impacted.length} impacted feature(s)`));
+        for (const row of impact.impacted)
+            out(`  ${row.feature}  ${pc.dim(row.reasons.join('; '))}`);
+        for (const row of impact.impacted)
+            filters.push(featureFilter(row.feature));
+    }
     // positional filters must precede `--project` (variadic in the runner CLI)
     args.splice(4, 0, ...filters);
     if (flags.list) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdods/cli",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "SDODS command line: run, record, analyze, agents, MCP server, scheduler and the web server.",
   "license": "Apache-2.0",
   "author": "SDODS <admin@sdods.com>",
@@ -23,8 +23,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@sdods/contracts": "0.2.2",
-    "@sdods/core": "0.2.2",
+    "@sdods/contracts": "0.3.1",
+    "@sdods/core": "0.3.1",
     "commander": "^15.0.0",
     "execa": "^10.0.1",
     "picocolors": "^1.1.1",
@@ -33,12 +33,12 @@
     "zod": "^4.5.4",
     "@playwright/test": "^1.62.1",
     "playwright-core": "^1.62.1",
-    "@sdods/integrations": "0.2.2",
-    "@sdods/mcp": "0.2.2",
-    "@sdods/agents": "0.2.2",
-    "@sdods/db": "0.2.2",
+    "@sdods/integrations": "0.3.1",
+    "@sdods/mcp": "0.3.1",
+    "@sdods/agents": "0.3.1",
+    "@sdods/db": "0.3.1",
     "csv-parse": "^7.0.2",
-    "@sdods/server": "0.2.2"
+    "@sdods/server": "0.3.1"
   },
   "homepage": "https://sdods.com",
   "bugs": {

package/templates/.claude/skills/sdods-release-channels/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: sdods-release-channels
+description: Publish SDODS through the package managers — Homebrew, Scoop, winget, npm, Docker/GHCR and the apt repository — and keep the install page honest about which of them actually work. Use when asked to add or fix a distribution channel, publish to a package manager, push the tap or bucket, submit the winget manifest, build the apt repo, or when a channel is missing from sdods.com/install.
+---
+
+# Distribution channels
+
+SDODS ships through six package managers on top of the two install scripts. They are **not one
+release**: they publish on three schedules, from two repositories, and two of them are published by
+someone who is not you.
+
+| Channel   | Publishes         | Where the manifest lives      | Who publishes it          |
+| --------- | ----------------- | ----------------------------- | ------------------------- |
+| npm       | the CLI           | — (`release.yml`)             | changesets, on `main`     |
+| Docker    | the server image  | — (`release.yml`)             | `release.yml`, after npm  |
+| Homebrew  | the CLI           | `siri1410/homebrew-sdods`     | you, `git push`           |
+| Scoop     | the desktop app   | `siri1410/scoop-sdods`        | you, `git push`           |
+| winget    | the desktop app   | `microsoft/winget-pkgs`       | **Microsoft's reviewers** |
+| apt       | the desktop app   | Pages on `sdods-releases`     | `apt.yml`, run by hand    |
+
+## The one rule
+
+**A channel goes live when its registry answers, not when its manifest is committed here.**
+
+`bun run channels:sync` probes each one — npm's registry, GHCR's anonymous pull token, the tap and
+bucket contents API, winget-pkgs, and the apt `InRelease` file — and writes the result into
+`apps/www/lib/install-channels.ts`. The install page renders live channels only, so a tab whose
+command would 404 cannot ship. Never flip a `live:` flag by hand; the flag is an observation.
+
+```bash
+bun run channels:sync
+```
+
+```bash
+bun run channels:sync -- --check   # non-zero if the committed state has drifted
+```
+
+Every SHA-256 in `packaging/` is computed from bytes the script downloaded. Do not transcribe one
+from a release page — it is the single field where being wrong means the package manager refuses
+to install at all, after every check here has passed.
+
+## The order things must happen in
+
+Two channels install the CLI from npm, and three install the desktop app from a release. Neither
+can be published before the thing it points at.
+
+```
+changesets publishes @sdods/cli  →  release.yml builds the GHCR image  →  channels:sync
+                                 →  Homebrew formula (npm tarball)     →  push the tap
+desktop-v* tag → workflow drafts → a PERSON publishes the release      →  channels:sync
+                                 →  Scoop, winget, apt manifests       →  push / submit / run apt.yml
+```
+
+## Per channel
+
+### npm — automatic
+
+`release.yml` runs changesets on every push to `main`. `scripts/publish-npm.sh` prints a
+`New tag: <pkg>@<version>` line per package, which is the **only** signal changesets/action reads
+to set its `published` output. Do not remove it: without it a successful publish reads as "nothing
+published" and the image job below never runs. That was the actual bug.
+
+### Docker — automatic, after npm
+
+Gated on `needs.changesets.outputs.published`, not on a `v*` tag. It used to gate on the tag and
+nothing in this repository creates one, so the job had never run and the image did not exist.
+Do not "fix" it by pushing a tag from CI: a tag pushed with `GITHUB_TOKEN` does not trigger
+workflows, so the job still would not run.
+
+**The image is `linux/amd64` only, and Docker does not emulate a missing architecture** — it
+refuses the pull with `no matching manifest for linux/arm64/v8`. Apple silicon needs
+`--platform linux/amd64`. Building arm64 in CI was tried and abandoned: under QEMU on an amd64
+runner the arm64 stage did not finish in 90 minutes, because `bun install`, the native module
+builds and the web bundle all run emulated. Fixing it properly means either a native arm64 runner
+(a paid tier for a private repository) or splitting the Dockerfile so the arch-independent web
+bundle builds on `$BUILDPLATFORM`. `channels:sync` reads the architectures out of the manifest and
+writes the note from them, so the page cannot claim an arch the image does not carry.
+
+**GHCR packages default to private, and visibility is a UI-only setting.** After the first push:
+Profile → Packages → `sdods-server` → Package settings → Change visibility → Public. Until then
+`channels:sync` reports `no anonymous pull token (403)` and the Docker tab stays hidden.
+
+### Homebrew — you push the tap
+
+```bash
+gh repo create siri1410/homebrew-sdods --public -d 'Homebrew tap for SDODS'
+```
+
+Copy the rendered formula into the tap as `Formula/sdods.rb`, then verify it locally before anyone
+installs from it. `--new` implies `--strict` and `--online` and is the check that catches a bad
+`url`, a redundant `version` or a foreign-architecture binary (it is `--new`, not `--new-formula`,
+which current Homebrew rejects):
+
+```bash
+brew audit --strict --new siri1410/sdods/sdods
+```
+
+```bash
+brew install --build-from-source siri1410/sdods/sdods && brew test sdods
+```
+
+You can do all of that without publishing anything: `brew tap-new siri1410/sdods --no-git` makes a
+local tap, and `brew untap siri1410/sdods` removes it.
+
+The formula builds from the **npm tarball**, not from a clone, which is why the private source
+repository is not a problem here.
+
+Three things about it are load-bearing, and each was found by running it rather than reading it:
+
+- **You cannot publish the formula the same day you publish the packages.** Homebrew's
+  `std_npm_args` passes `--min-release-age=`, so npm refuses any dependency published inside that
+  window: `No matching version found for @sdods/agents@X with a date before <date>`. The formula is
+  correct; it is too new. Wait for the packages to age out, then install.
+- **Foreign prebuilds must be deleted.** `better-sqlite3` ships prebuilt binaries for every
+  platform and npm installs all of them; audit then fails with *"Binaries built for a non-native
+  architecture were installed into sdods's prefix"*. The `install` block removes every
+  `prebuilds/*` directory but this machine's.
+- **`brew test` runs in an empty directory, so `sdods doctor` exits 1** — there are no projects to
+  find, which is the right answer for a fresh install. The test asserts exit `1` deliberately;
+  asserting `0` fails on a perfectly good install. It runs against Homebrew's `node`, which is
+  well ahead of 22 — that path is tested, and the native modules resolve on it.
+
+### Scoop — you push the bucket
+
+```bash
+gh repo create siri1410/scoop-sdods --public -d 'Scoop bucket for SDODS'
+```
+
+The manifest goes in as `bucket/sdods.json`. It installs the NSIS desktop installer silently with
+`/S /D=$dir`; `/D` must be last and unquoted, which is an NSIS rule — quote it and the install
+silently lands in the default directory instead of Scoop's.
+
+### winget — you can open the PR, not merge it
+
+```bash
+wingetcreate submit --token <PAT> packaging/winget
+```
+
+Then it sits in Microsoft's review queue. Expect friction: the installers are **unsigned**, and
+that is a thing their validation flags. See the `code-signing` skill — winget is the channel that
+most wants the certificate.
+
+### apt — a person runs the workflow
+
+`.github/workflows/apt.yml`, triggered manually. It needs `SDODS_APT_GPG_KEY` (the armoured
+private key of the **project** signing key, as a repository secret) and `DESKTOP_RELEASE_TOKEN`.
+It refuses to build unsigned: an unsigned repo can only be added with `[trusted=yes]`, which
+disables signature checking for everything else that machine installs.
+
+The workflow proves the repo works before publishing it — it adds the built repo as a local apt
+source and asserts `apt-cache policy sdods` reports an installable candidate. A repo that merely
+looks right has been verified zero times. The `apt · flat repo layout` job in `ci.yml` runs the
+same proof on every PR against a synthetic package, so the layout is exercised without a key.
+
+**It is a standard `dists/` repository, not a flat one, and that is load-bearing.** A flat repo is
+addressed with a `./` distribution, which puts a `./` segment into every path apt builds:
+
+```
+https://sdods.com/apt/./InRelease
+```
+
+Firebase Hosting answers that with a 302 to an internal origin host that 404s. The result is a
+repository where every file is served correctly to `curl` on the normalised path, and every real
+`apt update` fails with *"does not have a Release file"*. It shipped that way, and only an actual
+`apt install` in a container found it — checking that the files were reachable was not the same
+question.
+
+`build-repo.sh` also scans the pool directory by name rather than `.`, because `apt-ftparchive
+packages .` writes `Filename: ./pool/...` and that is the same broken segment one level down. And
+it splits the index per architecture with awk rather than `apt-ftparchive --arch`, which matches
+nothing here and silently writes an empty `Packages`.
+
+**GitHub Pages has to be enabled on the releases repository** — Settings → Pages → source
+`gh-pages` — or the workflow pushes the branch and the URL keeps 404ing.
+
+## Adding a seventh channel
+
+1. Add it to `INSTALL_CHANNELS` in `apps/www/lib/install-channels.ts` with `live: false`. Give it
+   `under:` if it belongs inside another tab's panel rather than owning a tab — Scoop and winget
+   sit under Windows because a visitor choosing how to install is choosing once, not three times.
+2. Add a probe in `scripts/sync-channels.ts` and wire it into the `live` map. A channel with no
+   probe can never go live, which is the correct failure.
+3. Put its manifest template in `packaging/<manager>/` with `{{PLACEHOLDER}}` fields.
+4. Add the command to the docs table in `getting-started/installation.mdx`.
+5. `bunx vitest run tests/install-channels.test.ts`.

package/templates/.claude/skills/code-signing/SKILL.md

@@ -1,238 +0,0 @@
----
-name: code-signing
-description: Obtain and wire code-signing certificates for the SDODS desktop app so macOS Gatekeeper and Windows SmartScreen stop blocking it. Use when asked about signing, notarization, Gatekeeper, SmartScreen, "app is damaged", "unidentified developer", Developer ID certificates, Azure Artifact Signing, or why the installers show security warnings.
----
-
-# Signing the SDODS desktop installers
-
-Unsigned installers work, but every user is told not to run them. macOS refuses a double-click
-("SDODS is damaged" or "unidentified developer") and Windows SmartScreen interrupts the install.
-That undercuts the one-click promise more than any technical problem in the app.
-
-**Everything in the build is already wired.** Supply the credentials as CI secrets and signing turns
-on with no code change. What cannot be automated is acquiring the certificates: both require a
-person's legal identity and a payment.
-
-Facts below were verified against Microsoft and Apple documentation in September 2026. Two pieces
-of widely repeated advice are now **wrong** — see the corrections at the end.
-
----
-
-## macOS — Gatekeeper
-
-### What to buy
-
-**Apple Developer Program, $99/year.** There is no free path that satisfies Gatekeeper. Enrol at
-<https://developer.apple.com/programs/>. Individual enrolment needs a legal name and payment;
-organisation enrolment additionally needs a D-U-N-S number and takes longer.
-
-### What to create
-
-A **Developer ID Application** certificate — *not* "Apple Distribution", which is for the App
-Store and will not satisfy Gatekeeper for direct download.
-
-1. Xcode → Settings → Accounts → Manage Certificates → **+** → Developer ID Application.
-   (Or Certificates, Identifiers & Profiles on the developer portal with a CSR.)
-2. Export it from Keychain Access as a `.p12` with a strong password.
-3. Base64 it for CI: `base64 -i cert.p12 | pbcopy`.
-
-### Notarization credentials
-
-Notarization is a separate step: Apple scans the signed app and issues a ticket. It needs an
-**app-specific password**, not your Apple ID password — create one at <https://appleid.apple.com>
-under Sign-In and Security. You also need your **Team ID** (developer portal → Membership).
-
-Locally, store credentials in the keychain once so the secret never reaches an env var or a log:
-
-```bash
-xcrun notarytool store-credentials sdods-notary \
-  --apple-id you@example.com --team-id ABCDE12345 --password <app-specific-password>
-```
-
-### CI secrets
-
-| Secret | Value |
-|---|---|
-| `MAC_CSC_LINK` | base64 of the `.p12` |
-| `MAC_CSC_KEY_PASSWORD` | the `.p12` password |
-| `APPLE_ID` | the Apple ID email |
-| `APPLE_APP_SPECIFIC_PASSWORD` | app-specific password |
-| `APPLE_TEAM_ID` | 10-character Team ID |
-
-`.github/workflows/desktop.yml` already passes all five. electron-builder signs and notarizes when
-they are present and silently skips when they are not, so unsigned builds keep working.
-
-### What is already correct in this repo
-
-- `hardenedRuntime: true` — required for notarization.
-- `entitlements` **and** `entitlementsInherit` both point at `build/entitlements.mac.plist`.
-- That plist sets `com.apple.security.cs.disable-library-validation`. **Do not remove it.** The app
-  runs `.node` native modules that npm downloads at runtime; to the hardened runtime those are
-  unsigned code, so without this the app notarizes successfully and then dies at first database
-  open with an opaque dyld error.
-- `mac.binaries` lists `Contents/Resources/node/bin/node`, so the bundled Node runtime is signed
-  too. A second executable inside the bundle is not signed automatically.
-
-### Timing
-
-`notarytool` typically returns in 2–10 minutes for a 100–200 MB bundle, ~15 at the 95th percentile.
-Around major macOS releases it can take 30–60. Budget for it in the release process; it is not a
-sign that something is wrong.
-
-### Verifying
-
-```bash
-codesign --verify --deep --strict --verbose=2 /Applications/SDODS.app
-spctl -a -vvv -t install /Applications/SDODS.app     # expect "accepted / Notarized Developer ID"
-xcrun stapler validate /Applications/SDODS.app
-```
-
-### Until certificates exist
-
-Users can bypass Gatekeeper themselves — right-click SDODS in Applications → **Open** → confirm.
-macOS remembers the choice. The download page prints this automatically while
-`DESKTOP_RELEASE.signed` is false. `xattr -dr com.apple.quarantine /Applications/SDODS.app` also
-works but is worse advice to give strangers.
-
----
-
-## Windows — SmartScreen
-
-### The gating question: where are you?
-
-**Azure Artifact Signing** (formerly Azure Trusted Signing) is the best option, but it is
-geographically restricted:
-
-- **Individual developers: USA and Canada only.**
-- Organisations: USA, Canada, EU, UK.
-
-If you are an individual outside the US/Canada, this route is closed and an OV certificate is the
-answer. Settle this before spending time on Azure — it determines the whole path.
-
-### Option A — Azure Artifact Signing (preferred where available)
-
-Generally available since April 2026. ~**$9.99/month** for 5,000 signatures and one certificate
-profile ($99.99/month for 100,000 and ten profiles) — cheaper than any traditional certificate,
-and **no hardware token**, which is what makes it work in CI at all.
-
-Individuals may now apply as self-employed; the 3-years-of-history requirement from the preview
-was dropped at GA. Identity validation runs through a third party (au10tix) and takes a few
-business days.
-
-Setup:
-
-1. Azure subscription → create an **Artifact Signing** account (pick the region nearest your CI).
-2. Complete identity validation. Assign yourself the **Identity Verifier** role — validation
-   cannot be completed without it, which is the usual place people get stuck.
-3. Create a **certificate profile** (type: Public Trust).
-4. Create a service principal for CI and grant it **Code Signing Certificate Profile Signer** on
-   the account.
-
-Then add to `apps/desktop/electron-builder.yml` under `win:`:
-
-```yaml
-win:
-  azureSignOptions:
-    publisherName: '<exact name on the certificate>'
-    endpoint: 'https://<region>.codesigning.azure.net/'
-    codeSigningAccountName: '<account>'
-    certificateProfileName: '<profile>'
-```
-
-and set `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET` as CI secrets.
-
-**Version note:** the block above is electron-builder v26 syntax, which is what this repo pins
-(26.15.3, the current release). v27 collapses Windows signing into a single `win.sign`
-discriminated union (`type: 'signtool' | 'hsm' | 'pkcs11' | 'azure'`) and removes
-`win.azureSignOptions` / `win.signtoolOptions`; `electron-builder migrate-schema` rewrites it.
-Check which major version is installed before copying config from a blog post.
-
-### Option B — OV certificate
-
-From DigiCert, Sectigo, GlobalSign and similar. **$150–300/year.**
-
-Since June 2023 the CA/Browser Forum requires the private key to live on an HSM or hardware token.
-That is the real cost: a USB token cannot be plugged into a GitHub-hosted runner, so you either use
-the CA's cloud HSM option or sign on a self-hosted runner. Choose a cloud-HSM product if you want
-CI signing at all.
-
-Wire it through the existing `WIN_CSC_LINK` / `WIN_CSC_KEY_PASSWORD` secrets, or the CA's own
-signing tool via a custom `sign` hook.
-
-### Option C — self-signed
-
-Testing and enterprise-managed fleets only. Windows does not trust it, so public users get a
-**stronger** block than with no signature at all. Never ship this publicly.
-
-### Reputation
-
-Signing does not remove SmartScreen warnings on day one. Reputation accrues to the publisher
-identity as releases are downloaded and run without incident. What matters is signing **every**
-release with the **same** identity — switching certificates resets the accumulated trust.
-
----
-
-## Linux
-
-No signing is required: AppImage and `.deb` install without any equivalent of Gatekeeper. Optional
-hardening if it becomes useful:
-
-- GPG-sign the `.deb` and publish the public key.
-- Ship a `.zsync` file beside the AppImage for delta updates.
-
-`SHA256SUMS.txt` already ships with every release, which is the verification most Linux users
-expect.
-
----
-
-## Two corrections to common advice
-
-**EV certificates no longer bypass SmartScreen.** They did — instantly, on first download — which
-is why almost every older guide recommends paying the EV premium for a new app. **Microsoft removed
-that behaviour in 2024.** EV-signed files now build reputation exactly like OV-signed ones. An
-existing EV certificate is still perfectly valid; buying one *specifically* to skip SmartScreen is
-no longer justified. (I gave this outdated advice earlier in this project.)
-
-**"Azure Trusted Signing" is now "Azure Artifact Signing."** Same service, renamed. Search results
-and documentation are split across both names, and the individual-developer eligibility rules
-changed at GA — preview-era pages saying individuals cannot sign up are out of date.
-
----
-
-## Is there a free option?
-
-**Windows: yes, but only for open source.** [SignPath Foundation](https://signpath.org/terms)
-gives qualifying projects free OV-level signing through a managed pipeline. Their conditions:
-
-- an **OSI-approved licence with no commercial dual-licensing** — Apache-2.0 qualifies;
-- **no proprietary or non-open-source components**, including code from the maintainer;
-- actively maintained, already released in the form to be signed, and functionality described on
-  the download page.
-
-SDODS is Apache-2.0, so the licence is fine — but the repository is **private**, and the programme
-is for open-source projects. Today it does not qualify. Making the source public would unlock it,
-and would also remove the need for the separate public releases repo and let the
-`NEXT_PUBLIC_REPO_PUBLIC` flags across both sites switch on. Applications take days to weeks.
-
-**macOS: no.** There is no free path to a Developer ID certificate or to notarization. A free Apple
-ID signs for local development only; the result still fails Gatekeeper on anyone else's Mac. The
-$99/year membership is unavoidable for direct distribution.
-
-**Linux: already free** — nothing to sign.
-
-So the realistic floors are **$99/year** (Apple, plus SignPath for Windows if the source goes
-public) or **~$219/year** (Apple plus Azure Artifact Signing at $9.99/month) with the source
-staying private.
-
----
-
-## After signing works
-
-1. Verify a real download on a machine that has never seen the app, not the build machine.
-2. Sync the download page with `--signed`, which removes the Gatekeeper/SmartScreen instructions:
-   ```bash
-   bun run desktop:sync-release desktop-v0.1.0 --signed
-   ```
-3. Enable `electron-updater` for the app shell. It was left off deliberately: Squirrel.Mac
-   **refuses to install an unsigned update**, so auto-update only becomes real once macOS signing
-   is in place. See the `sdods-desktop-release` skill.