de-shell 0.2.0__py3-none-any.whl

de_shell/js/main/pythonEnv.test.ts

@@ -0,0 +1,125 @@
+/**
+ * pythonEnv.test.ts — node:test unit tests for uv resolution.
+ *
+ * The dev-mode backend command used to be a bare 'uv', resolved by the OS at
+ * spawn time — so a uv that is installed but not on the app's PATH (the winget
+ * per-user install under an npm-run environment, the recurring case) failed as
+ * an opaque `spawn uv ENOENT`. `findUv` resolves uv to an absolute path up
+ * front: the PATH itself first, then the standard per-user install locations.
+ *
+ * Run: `node --test src/pythonEnv.test.ts` (from packages/shell-main/), or via
+ * the `test:unit` npm script.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, writeFileSync, mkdirSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+import { configureShell } from './config.ts'
+import { findUv, resolvePythonEnv } from './pythonEnv.ts'
+
+configureShell({
+  appId: 'testapp',
+  appName: 'Test App',
+  pythonModule: 'testapp',
+})
+
+/** A directory containing a uv stub under both spellings, so these tests do not
+ *  fork on the host platform. */
+function dirWithUv(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'uv-stub-'))
+  writeFileSync(join(dir, 'uv'), '')
+  writeFileSync(join(dir, 'uv.exe'), '')
+  return dir
+}
+
+function emptyDir(): string {
+  return mkdtempSync(join(tmpdir(), 'uv-none-'))
+}
+
+/** An env whose PATH and every fallback root point somewhere we control. */
+function envWith(overrides: Record<string, string>): Record<string, string> {
+  const nowhere = emptyDir()
+  return {
+    PATH: '',
+    HOME: nowhere,
+    USERPROFILE: nowhere,
+    LOCALAPPDATA: nowhere,
+    ...overrides,
+  }
+}
+
+test('findUv resolves uv from a PATH entry', () => {
+  const dir = dirWithUv()
+  const found = findUv(envWith({ PATH: dir }))
+  assert.ok(found, 'uv not found on PATH')
+  assert.ok(found.startsWith(dir), `${found} is not under ${dir}`)
+})
+
+test('findUv falls back to the standard per-user install dirs off PATH', () => {
+  const home = emptyDir()
+  mkdirSync(join(home, '.local', 'bin'), { recursive: true })
+  writeFileSync(join(home, '.local', 'bin', 'uv'), '')
+  writeFileSync(join(home, '.local', 'bin', 'uv.exe'), '')
+  const found = findUv(envWith({ HOME: home, USERPROFILE: home }))
+  assert.ok(found, 'uv not found in ~/.local/bin')
+  assert.ok(found.startsWith(join(home, '.local', 'bin')))
+})
+
+test('findUv finds a winget-linked uv via LOCALAPPDATA', () => {
+  const localAppData = emptyDir()
+  const links = join(localAppData, 'Microsoft', 'WinGet', 'Links')
+  mkdirSync(links, { recursive: true })
+  writeFileSync(join(links, 'uv'), '')
+  writeFileSync(join(links, 'uv.exe'), '')
+  const found = findUv(envWith({ LOCALAPPDATA: localAppData }))
+  assert.ok(found, 'uv not found in the winget Links dir')
+  assert.ok(found.startsWith(links))
+})
+
+test('findUv returns null when uv is nowhere', () => {
+  assert.equal(findUv(envWith({})), null)
+})
+
+test('dev-mode resolvePythonEnv spawns the resolved absolute uv', async () => {
+  const dir = dirWithUv()
+  const saved = { PATH: process.env.PATH, HOME: process.env.HOME,
+                  USERPROFILE: process.env.USERPROFILE, LOCALAPPDATA: process.env.LOCALAPPDATA }
+  try {
+    Object.assign(process.env, envWith({ PATH: dir }))
+    const resolved = await resolvePythonEnv({
+      isPackaged: false,
+      resourcesPath: emptyDir(),
+      projectRoot: emptyDir(),
+      userData: emptyDir(),
+    })
+    assert.ok(resolved.cmd[0].startsWith(dir),
+      `expected an absolute uv under ${dir}, got ${resolved.cmd[0]}`)
+    assert.deepEqual(resolved.cmd.slice(1), ['run', 'python', '-m', 'testapp'])
+  } finally {
+    for (const [k, v] of Object.entries(saved)) {
+      if (v === undefined) delete process.env[k]
+      else process.env[k] = v
+    }
+  }
+})
+
+test('dev-mode resolvePythonEnv leaves a bare uv when none is found (the spawn trap reports it)', async () => {
+  const saved = { PATH: process.env.PATH, HOME: process.env.HOME,
+                  USERPROFILE: process.env.USERPROFILE, LOCALAPPDATA: process.env.LOCALAPPDATA }
+  try {
+    Object.assign(process.env, envWith({}))
+    const resolved = await resolvePythonEnv({
+      isPackaged: false,
+      resourcesPath: emptyDir(),
+      projectRoot: emptyDir(),
+      userData: emptyDir(),
+    })
+    assert.equal(resolved.cmd[0], 'uv')
+  } finally {
+    for (const [k, v] of Object.entries(saved)) {
+      if (v === undefined) delete process.env[k]
+      else process.env[k] = v
+    }
+  }
+})

de_shell/js/main/pythonEnv.ts

@@ -0,0 +1,442 @@
+/**
+ * pythonEnv.ts — resolve (and on first run, create) the Python sidecar env.
+ *
+ * The uv-managed distribution model: the installer ships a tiny
+ * payload — the bundled `uv`, the project (`pyproject.toml` + `uv.lock`) and the
+ * app's Python source — under <resources>/python. On first launch we run
+ * `uv sync` into a venv in the user's WRITABLE data dir (the app bundle is
+ * read-only / code-signed), so the GPU-correct torch wheel is fetched per
+ * machine and updates are a cheap incremental `uv sync`.
+ *
+ * torch is resolved PER MACHINE (win32/linux): the lock pins torch to the cu124
+ * index (the dev box's backend), which would force the cu124 wheel onto every
+ * user. Instead the first-run install is two-step:
+ *   1. `uv sync --frozen --no-dev --no-install-package torch`  (lock-exact for
+ *      everything EXCEPT torch)
+ *   2. `uv pip install torch==<locked release> --torch-backend=auto
+ *       --python <env python>`  (uv probes the machine's driver and picks the
+ *      matching CUDA / CPU wheel — verified: `--python` is required, uv pip
+ *      IGNORES UV_PROJECT_ENVIRONMENT; needs uv >= 0.5, the staged uv is 0.10.x)
+ * Any step-2 failure falls back to the plain full `uv sync` (the old cu124
+ * path), so the working install path can never regress. macOS keeps the plain
+ * sync (no CUDA pin there; PyPI torch already carries MPS).
+ *
+ * In development (no bundled payload) we fall back to `uv run` from the repo
+ * root — exactly the previous behaviour.
+ */
+import { spawn } from 'child_process'
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs'
+import { createHash } from 'crypto'
+import { join } from 'path'
+// Extension spelled out so node:test can load this module without a bundler
+// (native type-stripping resolves relative imports literally).
+import { shellConfig } from './config.ts'
+
+export interface ResolvedPython {
+  cmd: string[]      // argv to spawn, e.g. [pythonExe, '-m', 'spyde']  (module from ShellConfig)
+  cwd: string        // working directory for the spawn
+}
+
+export interface EnsureOptions {
+  isPackaged: boolean
+  resourcesPath: string   // process.resourcesPath (packaged) — holds <…>/python
+  projectRoot: string     // repo root (dev) — holds pyproject.toml
+  userData: string        // app.getPath('userData') — writable venv lives here
+  onProgress?: (line: string) => void
+}
+
+const isWin = process.platform === 'win32'
+
+export function venvPython(envDir: string): string {
+  return isWin ? join(envDir, 'Scripts', 'python.exe') : join(envDir, 'bin', 'python')
+}
+
+function uvBinaryName(): string {
+  return isWin ? 'uv.exe' : 'uv'
+}
+
+/**
+ * Resolve uv to an ABSOLUTE path: each PATH entry first, then the standard
+ * per-user install locations that a spawned app's PATH routinely misses —
+ * winget's Links dir (win32), `~/.local/bin` (uv's own installer) and
+ * `~/.cargo/bin` (cargo installs). Returns null when uv is nowhere; the caller
+ * keeps the bare 'uv' so the spawn-error trap reports the absence readably
+ * instead of this module deciding startup policy.
+ *
+ * `env` is injectable for tests; both binary spellings are tried on every
+ * platform so the resolution logic itself stays platform-agnostic.
+ */
+export function findUv(env: NodeJS.ProcessEnv = process.env): string | null {
+  const names = ['uv.exe', 'uv']
+  const pathVar = env.PATH ?? env.Path ?? ''
+  const home = env.HOME ?? env.USERPROFILE ?? ''
+  const candidates = [
+    ...pathVar.split(isWin ? ';' : ':').filter(Boolean),
+    ...(env.LOCALAPPDATA ? [join(env.LOCALAPPDATA, 'Microsoft', 'WinGet', 'Links')] : []),
+    ...(home ? [join(home, '.local', 'bin'), join(home, '.cargo', 'bin')] : []),
+  ]
+  for (const dir of candidates) {
+    for (const name of names) {
+      const p = join(dir, name)
+      if (existsSync(p)) return p
+    }
+  }
+  return null
+}
+
+/** Paths of the bundled project + managed env, and whether each exists — the
+ *  single "is there a managed environment?" answer, shared by the first-run
+ *  setup and the GPU-triage Fix handler (index.ts). In dev there is no bundled
+ *  payload, so `bundled` is false and the triage UI goes report-only. */
+export function managedEnvPaths(resourcesPath: string, userData: string): {
+  projectDir: string
+  envDir: string
+  pythonExe: string
+  bundled: boolean
+  envExists: boolean
+} {
+  const projectDir = join(resourcesPath, 'python')
+  const envDir = join(userData, 'python-env')
+  const pythonExe = venvPython(envDir)
+  return {
+    projectDir,
+    envDir,
+    pythonExe,
+    bundled: existsSync(join(projectDir, 'uv.lock')),
+    envExists: existsSync(pythonExe),
+  }
+}
+
+/**
+ * The locked torch release for THIS platform, parsed from `<projectDir>/uv.lock`.
+ *
+ * The lock carries TWO torch entries (platform-conditional sources): the
+ * `download.pytorch.org/whl/cu124` one (win32 per pyproject's source marker,
+ * e.g. "2.6.0+cu124") and the PyPI one (everything else, e.g. "2.13.0"). Pick
+ * the entry whose source matches this platform and strip any `+cuXXX` local
+ * tag — `--torch-backend=auto` owns the backend variant; we only pin the
+ * release so the resolved wheel stays lock-adjacent. torch is the ONLY
+ * torch-family package in the lock (no torchvision/torchaudio), so one
+ * `--no-install-package torch` + one pip install covers the family. Returns
+ * null when the lock is missing/unparseable (caller uses the plain full sync).
+ */
+export function readLockedTorchVersion(projectDir: string): string | null {
+  const lock = readSafe(join(projectDir, 'uv.lock'))
+  if (!lock) return null
+  // Each entry: [[package]] \n name = "torch" \n version = "…" \n source = { registry = "…" }
+  const re = /\[\[package\]\]\s*\r?\nname = "torch"\s*\r?\nversion = "([^"]+)"\s*\r?\nsource = \{ registry = "([^"]+)" \}/g
+  const entries: Array<{ version: string; registry: string }> = []
+  for (let m = re.exec(lock); m; m = re.exec(lock)) {
+    entries.push({ version: m[1], registry: m[2] })
+  }
+  if (!entries.length) return null
+  const preferPytorchIndex = isWin   // pyproject pins the cu124 index for win32 only
+  const pick =
+    entries.find((e) => preferPytorchIndex === e.registry.includes('download.pytorch.org')) ??
+    entries[0]
+  return pick.version.split('+')[0]   // "2.6.0+cu124" → "2.6.0"
+}
+
+/** Resolve the command to launch the app's backend, creating the venv if needed. */
+export async function resolvePythonEnv(opts: EnsureOptions): Promise<ResolvedPython> {
+  const cfg = shellConfig()
+  const bundledProject = join(opts.resourcesPath, 'python')
+  const bundledLock = join(bundledProject, 'uv.lock')
+
+  // Development (or any build without the staged payload): resolve uv up front
+  // — PATH, then the standard per-user install dirs — so a uv that is installed
+  // but off this process's PATH still works. When it is truly nowhere, keep the
+  // bare 'uv': the spawn-error trap turns that into a readable report.
+  if (!opts.isPackaged || !existsSync(bundledLock)) {
+    const uv = findUv() ?? 'uv'
+    return { cmd: [uv, 'run', 'python', '-m', cfg.pythonModule], cwd: opts.projectRoot }
+  }
+
+  const envDir = join(opts.userData, 'python-env')
+  const pythonExe = venvPython(envDir)
+  const stampFile = join(envDir, `.${cfg.appId}-lock-hash`)
+  const lockHash = createHash('sha256').update(readFileSync(bundledLock)).digest('hex')
+
+  // Skip the sync if the venv already matches the shipped lock.
+  const upToDate =
+    existsSync(pythonExe) &&
+    existsSync(stampFile) &&
+    readSafe(stampFile) === lockHash
+
+  if (!upToDate) {
+    await setupEnv(bundledProject, envDir, readAppVersion(bundledProject), opts.onProgress)
+    try {
+      mkdirSync(envDir, { recursive: true })
+      writeFileSync(stampFile, lockHash, 'utf8')
+    } catch { /* a missing stamp just forces a re-sync next launch */ }
+  }
+
+  return { cmd: [pythonExe, '-m', cfg.pythonModule], cwd: bundledProject }
+}
+
+function readSafe(p: string): string {
+  try { return readFileSync(p, 'utf8').trim() } catch { return '' }
+}
+
+/**
+ * The version bundle-python.mjs baked into `<projectDir>/.<appId>-version`
+ * (X.Y.Z, resolved at CI bundle time when git history exists). Empty string in
+ * dev (no marker) — the dev repo has `.git`, so setuptools_scm works normally.
+ */
+function readAppVersion(projectDir: string): string {
+  return readSafe(join(projectDir, `.${shellConfig().appId}-version`))
+}
+
+/**
+ * Build the env for a uv invocation against the managed env.
+ *
+ * `appVersion` (from the .<appId>-version marker) is exported as
+ * SETUPTOOLS_SCM_PRETEND_VERSION_FOR_<DIST> so building the editable app package
+ * succeeds even though the staged tree has NO `.git` — without it
+ * setuptools_scm raises `LookupError: unable to detect version` and `uv sync`
+ * exits 1 (the first-launch crash). Absent in dev (marker not present) → the
+ * env is unchanged and setuptools_scm resolves from the repo's git history.
+ */
+function uvEnv(envDir: string, appVersion: string, projectDir?: string): NodeJS.ProcessEnv {
+  // Pretend-version env for setuptools_scm. The dist-name–scoped var is the
+  // precise one; the plain SETUPTOOLS_SCM_PRETEND_VERSION is a harmless
+  // belt-and-braces fallback in case the dist name ever changes.
+  //
+  // setuptools_scm normalises the dist name to the env-var suffix by
+  // uppercasing and replacing runs of non-alphanumerics with `_`
+  // ("de-shell" → "DE_SHELL", "spyde" → "SPYDE").
+  const scmSuffix = String(shellConfig().pythonDist)
+    .toUpperCase().replace(/[^A-Z0-9]+/g, '_')
+  const scmEnv: Record<string, string> = appVersion
+    ? {
+        [`SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${scmSuffix}`]: appVersion,
+        SETUPTOOLS_SCM_PRETEND_VERSION: appVersion,
+      }
+    : {}
+  // Put the vendored portable git (bundle-python.mjs staged it at
+  // <projectDir>/git) on PATH so `uv sync` can resolve `git+https://…` deps
+  // (the hyperspy fork) on machines with no system git. MinGit's launcher is in
+  // git/cmd on Windows; git/bin holds it on posix. Prepend so ours wins; fall
+  // through to any system git if the vendored one is absent (dev builds).
+  const gitDir = projectDir ? join(projectDir, 'git') : ''
+  const gitBins = gitDir
+    ? [join(gitDir, 'cmd'), join(gitDir, 'bin')].filter((d) => existsSync(d))
+    : []
+  const pathKey = isWin ? 'Path' : 'PATH'
+  const basePath = process.env[pathKey] ?? process.env.PATH ?? ''
+  const mergedPath = gitBins.length
+    ? [...gitBins, basePath].join(isWin ? ';' : ':')
+    : basePath
+
+  return {
+    ...process.env,
+    ...scmEnv,
+    [pathKey]: mergedPath,
+    // UV_PROJECT_ENVIRONMENT redirects `uv sync`'s venv out of the read-only
+    // resources into the writable user dir. (Ignored by `uv pip install`,
+    // which targets via --python — verified; harmless to set for both.)
+    UV_PROJECT_ENVIRONMENT: envDir,
+    // Keep uv's own cache/tools next to the env so an air-gapped re-run is
+    // self-contained and we never write into the read-only bundle.
+    UV_CACHE_DIR: join(envDir, '..', 'uv-cache'),
+  }
+}
+
+/** Spawn the bundled (or PATH) uv with `args`, streaming output to onProgress. */
+function runUv(
+  projectDir: string,
+  envDir: string,
+  args: string[],
+  appVersion: string,
+  onProgress?: (line: string) => void,
+): Promise<void> {
+  const uv = join(projectDir, uvBinaryName())
+  // Fall back to a resolved PATH/per-user uv if not bundled (dev builds).
+  const uvCmd = existsSync(uv) ? uv : (findUv() ?? 'uv')
+  return new Promise((resolve, reject) => {
+    const proc = spawn(uvCmd, args, {
+      cwd: projectDir,
+      env: uvEnv(envDir, appVersion, projectDir),
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    const relay = (b: Buffer) => onProgress?.(b.toString())
+    proc.stdout?.on('data', relay)
+    proc.stderr?.on('data', relay)   // uv prints progress to stderr
+    proc.on('error', reject)
+    proc.on('close', (code) =>
+      code === 0 ? resolve() : reject(new Error(`uv ${args[0]} exited with code ${code}`)),
+    )
+  })
+}
+
+/**
+ * Install the locked torch release into the managed env with the backend
+ * resolved for THIS machine (`--torch-backend=auto`: uv probes the NVIDIA
+ * driver and picks the matching cuXXX wheel, or the much smaller CPU wheel when
+ * no GPU is present). Shared by first-run setup (step 2) and the GPU-triage
+ * "Fix PyTorch install" handler. Throws on failure (caller decides fallback).
+ */
+export function installTorchPerMachine(
+  projectDir: string,
+  envDir: string,
+  onProgress?: (line: string) => void,
+): Promise<void> {
+  const torchVersion = readLockedTorchVersion(projectDir)
+  if (!torchVersion) {
+    return Promise.reject(new Error('could not read the locked torch version from uv.lock'))
+  }
+  onProgress?.(`[env-setup] installing torch==${torchVersion} with --torch-backend=auto\n`)
+  return runUv(
+    projectDir, envDir,
+    ['pip', 'install', `torch==${torchVersion}`, '--torch-backend=auto',
+     '--python', venvPython(envDir)],
+    '',   // no scm pretend-version needed for a plain pip install
+    onProgress,
+  )
+}
+
+/** The pre-built app wheel staged by bundle-python.mjs at <projectDir>/wheels/
+ *  (a single py3-none-any .whl). Null in dev (no staged wheel) → the caller
+ *  installs the project from source the old way (dev tree is writable).
+ *
+ *  Matched by the DIST name with its separators normalised: a wheel filename
+ *  uses `_` where the dist name may use `-` ("de-shell" → "de_shell-0.1.0-…"). */
+function stagedAppWheel(projectDir: string): string | null {
+  const dir = join(projectDir, 'wheels')
+  if (!existsSync(dir)) return null
+  const prefix = String(shellConfig().pythonDist).replace(/-/g, '_').toLowerCase()
+  try {
+    const whl = readdirSync(dir).find(
+      (f) => f.toLowerCase().replace(/-/g, '_').startsWith(prefix) && f.endsWith('.whl'),
+    )
+    return whl ? join(dir, whl) : null
+  } catch { return null }
+}
+
+/**
+ * Every wheel staged beside the app's own — the workspace MEMBERS.
+ *
+ * The app is one package in a uv workspace, and its siblings are path
+ * dependencies. They cannot be built on the user's machine for the same reason
+ * the app cannot (setuptools' egg_info writes into a read-only tree), so
+ * `bundle-python.mjs` builds them all with `uv build --all-packages` and they
+ * are installed from wheels here.
+ */
+function stagedMemberWheels(projectDir: string, appWheel: string | null): string[] {
+  const dir = join(projectDir, 'wheels')
+  if (!existsSync(dir)) return []
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith('.whl'))
+      .map((f) => join(dir, f))
+      .filter((f) => f !== appWheel)
+  } catch { return []; }
+}
+
+/**
+ * The distribution name a wheel file installs, from its filename.
+ *
+ * Wheel names are `{name}-{version}-…`, and the name has `-` normalised to `_`.
+ * uv accepts either spelling for `--no-install-package`.
+ */
+function wheelPackageName(wheel: string): string {
+  return (wheel.split(/[\\/]/).pop() || '').split('-')[0]
+}
+
+/**
+ * Install the PRE-BUILT app wheel into the managed env with no dependency
+ * resolution (`--no-deps` — the sync already installed every dependency). This
+ * is the whole reason the wheel exists: it avoids building the app from the
+ * read-only shipped source tree (setuptools' egg_info write → "Access is
+ * denied", the rc.2/rc.3 first-launch crash). Throws on failure.
+ */
+function installAppWheel(
+  projectDir: string,
+  envDir: string,
+  wheel: string,
+  onProgress?: (line: string) => void,
+): Promise<void> {
+  onProgress?.(
+    `[env-setup] installing ${shellConfig().pythonDist} from wheel ` +
+    `${wheel.split(/[\\/]/).pop()}\n`,
+  )
+  return runUv(
+    projectDir, envDir,
+    ['pip', 'install', '--no-deps', '--python', venvPython(envDir), wheel],
+    '', onProgress,
+  )
+}
+
+/**
+ * Create/refresh the managed env. On win32/linux (the platforms where the lock
+ * pins CUDA torch) this is the two-step per-machine install; on failure — or on
+ * macOS, or when the lock has no readable torch pin — the plain full
+ * `uv sync --frozen --no-dev` (the original, known-good path) runs instead.
+ *
+ * When a pre-built app wheel is staged (the packaged app), the syncs use
+ * `--no-install-project` (resolve + install DEPS only, never build the app) and
+ * the app is installed from the wheel afterwards — so NOTHING is built from the
+ * read-only source tree. In dev (no staged wheel) the project installs from
+ * source as before. Logs which path ran to the progress stream.
+ */
+async function setupEnv(
+  projectDir: string,
+  envDir: string,
+  appVersion: string,
+  onProgress?: (line: string) => void,
+): Promise<void> {
+  const wheel = stagedAppWheel(projectDir)
+  const memberWheels = stagedMemberWheels(projectDir, wheel)
+  // With a staged wheel, tell uv sync NOT to touch the project (the app builds
+  // from the read-only tree otherwise); we install the wheel separately.
+  //
+  // `--no-install-project` covers the ROOT project only, so every workspace
+  // MEMBER needs excluding by name as well. Without that, uv tries to build
+  // them from the payload — which carries their pyproject.toml for workspace
+  // discovery and nothing else — and first launch dies before installing
+  // anything ("Distribution not found at: file:///…/packages/de-shell").
+  const projectArgs = wheel ? ['--no-install-project'] : ['--no-editable']
+  for (const memberWheel of memberWheels) {
+    projectArgs.push('--no-install-package', wheelPackageName(memberWheel))
+  }
+
+  const twoStep =
+    (process.platform === 'win32' || process.platform === 'linux') &&
+    readLockedTorchVersion(projectDir) !== null
+
+  if (twoStep) {
+    try {
+      onProgress?.('[env-setup] two-step install: uv sync (lock-exact, torch deferred) '
+        + 'then torch via --torch-backend=auto\n')
+      // Step 1: every DEPENDENCY except torch, exactly as locked. torch is the
+      // only torch-family package in the lock, so one exclusion covers it.
+      await runUv(
+        projectDir, envDir,
+        ['sync', '--frozen', '--no-dev', ...projectArgs, '--no-install-package', 'torch'],
+        appVersion, onProgress,
+      )
+      // Step 2: torch resolved for this machine.
+      await installTorchPerMachine(projectDir, envDir, onProgress)
+      // Step 3: the workspace members, then the app — all from pre-built
+      // wheels (packaged only). Members first: the app wheel depends on them
+      // and `--no-deps` means nothing else will pull them in.
+      for (const memberWheel of memberWheels) {
+        await installAppWheel(projectDir, envDir, memberWheel, onProgress)
+      }
+      if (wheel) await installAppWheel(projectDir, envDir, wheel, onProgress)
+      onProgress?.('[env-setup] per-machine torch install complete\n')
+      return
+    } catch (err) {
+      onProgress?.(`[env-setup] per-machine torch install failed (${(err as Error)?.message ?? err}); `
+        + 'falling back to the full locked sync\n')
+      // fall through to the plain sync
+    }
+  }
+
+  onProgress?.('[env-setup] running full locked uv sync\n')
+  await runUv(projectDir, envDir, ['sync', '--frozen', '--no-dev', ...projectArgs], appVersion, onProgress)
+  for (const memberWheel of memberWheels) {
+    await installAppWheel(projectDir, envDir, memberWheel, onProgress)
+  }
+  if (wheel) await installAppWheel(projectDir, envDir, wheel, onProgress)
+}

de_shell/js/main/sentryEnvelope.test.ts

@@ -0,0 +1,94 @@
+/**
+ * sentryEnvelope.test.ts — node:test unit tests for the problem-report wire
+ * format.
+ *
+ * This file is hand-written against a protocol, so the tests stand in for the
+ * SDK that would otherwise be guaranteeing it. They pin the two things a
+ * malformed report would fail on silently — the envelope's byte-length framing
+ * and the auth header — and the DSN parse, whose whole job is to fail softly so
+ * a build with no DSN configured still writes reports to disk.
+ *
+ * Run: `node --test src/sentryEnvelope.test.ts`, or via the `test:unit` script.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  buildEnvelope, formatEventId, parseSentryDsn, sentryAuthHeader,
+} from './sentryEnvelope.ts'
+
+test('parses a modern DSN into endpoint, key and project', () => {
+  const target = parseSentryDsn('https://abc123@o44.ingest.sentry.io/1234567')
+  assert.equal(target?.endpoint, 'https://o44.ingest.sentry.io/api/1234567/envelope/')
+  assert.equal(target?.publicKey, 'abc123')
+  assert.equal(target?.dsn, 'https://abc123@o44.ingest.sentry.io/1234567')
+})
+
+test('drops the secret from a legacy key:secret DSN', () => {
+  const target = parseSentryDsn('https://pub:secret@o44.ingest.sentry.io/9')
+  assert.equal(target?.publicKey, 'pub')
+  assert.ok(!target?.dsn.includes('secret'), 'the secret must not be echoed back')
+})
+
+test('a self-hosted DSN keeps its port and host', () => {
+  const target = parseSentryDsn('https://key@sentry.example.org:8443/42')
+  assert.equal(target?.endpoint, 'https://sentry.example.org:8443/api/42/envelope/')
+})
+
+test('an absent or unusable DSN yields null rather than throwing', () => {
+  // Each of these must leave the app in the "write to disk only" mode.
+  for (const dsn of [
+    undefined, null, '', '   ',
+    'not-a-url',
+    'https://o44.ingest.sentry.io/1234567',   // no public key
+    'https://abc123@o44.ingest.sentry.io/',   // no project id
+    'https://abc123@o44.ingest.sentry.io/notanumber',
+    'ftp://abc123@o44.ingest.sentry.io/1',    // not HTTP
+  ]) {
+    assert.equal(parseSentryDsn(dsn as string | undefined), null, `should reject: ${String(dsn)}`)
+  }
+})
+
+test('auth header carries version, client and key', () => {
+  const target = parseSentryDsn('https://abc123@o44.ingest.sentry.io/1')!
+  const header = sentryAuthHeader(target, 'spyde-shell/1.0')
+  assert.match(header, /^Sentry sentry_version=7/)
+  assert.match(header, /sentry_client=spyde-shell\/1\.0/)
+  assert.match(header, /sentry_key=abc123/)
+})
+
+test('event ids are 32 lowercase hex characters', () => {
+  const id = formatEventId(Uint8Array.from({ length: 16 }, (_, i) => i))
+  assert.match(id, /^[0-9a-f]{32}$/)
+  assert.equal(id, '000102030405060708090a0b0c0d0e0f')
+})
+
+test('a short byte array is padded rather than producing a short id', () => {
+  assert.match(formatEventId(new Uint8Array([1, 2])), /^[0-9a-f]{32}$/)
+})
+
+test('envelope framing is three newline-delimited JSON lines', () => {
+  const target = parseSentryDsn('https://abc123@o44.ingest.sentry.io/7')!
+  const event = { event_id: 'a'.repeat(32), message: 'boom' }
+  const lines = buildEnvelope(target, event, '2026-08-28T00:00:00.000Z').split('\n')
+
+  const envelopeHeader = JSON.parse(lines[0])
+  assert.equal(envelopeHeader.event_id, 'a'.repeat(32))
+  assert.equal(envelopeHeader.dsn, target.dsn)
+
+  const itemHeader = JSON.parse(lines[1])
+  assert.equal(itemHeader.type, 'event')
+
+  assert.deepEqual(JSON.parse(lines[2]), event)
+  assert.equal(lines[3], '', 'the envelope ends with a newline')
+})
+
+test('the item length is BYTES, not characters', () => {
+  // A report naming a file with an accent, or a stack trace with a smart quote,
+  // is rejected outright if this counts characters — hence the explicit test.
+  const target = parseSentryDsn('https://abc123@o44.ingest.sentry.io/7')!
+  const event = { event_id: 'b'.repeat(32), message: 'Ångström — µm' }
+  const lines = buildEnvelope(target, event, '2026-08-28T00:00:00.000Z').split('\n')
+  const declared = JSON.parse(lines[1]).length
+  assert.equal(declared, Buffer.byteLength(lines[2], 'utf8'))
+  assert.ok(declared > lines[2].length, 'multi-byte content must declare more bytes than characters')
+})