dsh-wsl-desktop 0.7.0 → 0.7.1

package/README.en.md

@@ -155,6 +155,7 @@ These are real boundaries, not a disclaimer list. Each one tells you where to re
 - [Diagnostics](docs/DIAGNOSTICS.md) — error codes, the health check, degradation and the privacy boundary
 - [Engineering notes](docs/ENGINEERING-NOTES.md) — measured constraints, repository layout, release flow, install shape
 - [Distro support matrix](docs/DISTRO-SUPPORT.md) — which distros were verified, and what each one needs
+- [Compatibility and upgrades](docs/COMPATIBILITY.md) — plugin/desktop version relation, upgrade order, rollback steps
 - [Upstream API proposals](docs/UPSTREAM-PROPOSALS.md) — the two proposals to the harness upstream
 - [Architecture and flow diagrams](docs/diagrams.md) — interactive architecture, sequence and lifecycle diagrams
 

package/README.md

@@ -128,6 +128,7 @@ plugin_manager install_bundle dsh-wsl-desktop@<version>
 - [诊断](docs/DIAGNOSTICS.md) — 错误码、环境检查、宿主能力缺失时的降级与隐私边界
 - [工程笔记](docs/ENGINEERING-NOTES.md) — 实测约束、仓库布局、发版流程、安装形态
 - [发行版支持矩阵](docs/DISTRO-SUPPORT.md) — 哪些发行版验证过，每种缺什么
+- [兼容性与升级](docs/COMPATIBILITY.md) — 插件与桌面的版本关系、升级顺序、回退步骤
 - [上游 API 提案](docs/UPSTREAM-PROPOSALS.md) — 对 harness 上游的两项提案
 - [架构与流程图](docs/diagrams.md) — 可交互的架构、时序与生命周期图
 

package/lib/client.js

@@ -119,6 +119,10 @@ window.__ModuleLoader__.load({
       healthWarn: { zh: '，{count} 项建议处理', en: ', {count} advisory' },
       healthFail: { zh: '，{count} 项失败', en: ', {count} failed' },
       dialogDescription: { zh: '从 WSL 发行版目录创建工作区。', en: 'Create a workspace from a WSL distribution directory.' },
+      filterPlaceholder: { zh: '过滤当前目录…', en: 'Filter this directory…' },
+      filterLabel: { zh: '按名称过滤目录', en: 'Filter directories by name' },
+      filterEmpty: { zh: '没有匹配的子目录', en: 'No matching subdirectories' },
+      retryList: { zh: '重试读取', en: 'Try again' },
     }
 
     /**
@@ -524,7 +528,7 @@ window.__ModuleLoader__.load({
      * @param {object|null} bootstrap - the bootstrap result.
      * @returns {HTMLElement|null} the node.
      */
-    function renderFailureNode(failure, bootstrap) {
+    function renderFailureNode(failure, bootstrap, state = null) {
       if (failure === null) return null
       const catalog = bootstrap?.ok === true ? bootstrap.value?.catalog : null
       const entry = catalog?.codes?.[failure.code]
@@ -570,9 +574,64 @@ window.__ModuleLoader__.load({
         box.append(link)
       }
       box.append(el('div', { fontSize: '11px', color: T.dim }, failure.code))
+      if (state !== null) {
+        // A failed browse or commit used to offer no report at all; only the
+        // degraded card did. The same report is now one click away on every
+        // failure, with the same redaction rules.
+        const copyAll = el('button', { ...BUTTON_STYLE, padding: '2px 8px', fontSize: '11px', alignSelf: 'flex-start' },
+          t('复制诊断', 'Copy diagnostics'))
+        copyAll.type = 'button'
+        copyAll.setAttribute('data-wsl-diagnostics', '')
+        copyAll.addEventListener('click', () => {
+          void navigator.clipboard?.writeText?.(buildDiagnostics(state, failure))
+          copyAll.textContent = t('已复制', 'Copied')
+          announce(t('已复制', 'Copied'))
+        })
+        box.append(copyAll)
+      }
       return box
     }
 
+    /**
+     * Build the copyable diagnostic report.
+     *
+     * Deliberately excludes the host message, stderr, resolved paths and the raw
+     * failure text: it carries only what the catalog already exposes plus the
+     * doctor's path-free facts. A failure is described by its code and params.
+     * @param {object} state - the open picker's state.
+     * @param {object|null} [failure] - the failure to include, if any.
+     * @returns {string} pretty JSON.
+     */
+    function buildDiagnostics(state, failure = null) {
+      const bootstrap = state.bootstrap
+      const value = bootstrap?.ok === true ? bootstrap.value : null
+      const health = state.health?.status === 'ready'
+        ? {
+          distro: state.health.distro ?? state.distro,
+          user: state.health.user ?? state.user,
+          family: state.health.family ?? null,
+          runner: state.health.runner ?? null,
+          restricted: state.health.restricted ?? null,
+          checks: (state.health.checks ?? []).map((entry) => ({
+            id: entry.id,
+            status: entry.status,
+            ...(typeof entry.detail === 'string' ? { detail: entry.detail } : {}),
+          })),
+        }
+        : null
+      return JSON.stringify({
+        schema: 1,
+        locale: LOCALE,
+        pluginVersion: value?.pluginVersion ?? 'unknown',
+        catalog: value === null ? 'unavailable' : 'loaded',
+        capabilities: value?.capabilities ?? null,
+        features: state.features,
+        missing: state.missing,
+        health,
+        error: failure === null ? null : { code: failure.code, params: failure.params ?? {} },
+      }, null, 2)
+    }
+
     /**
      * The degraded card: what is missing, what to do, and a copyable report.
      * @param {object[]} body - the card's child list.
@@ -603,11 +662,7 @@ window.__ModuleLoader__.load({
       const entry = catalog?.codes?.['host-capability-missing']
       const remedy = entry === undefined ? null : renderRemedy(entry.remedy)
       if (remedy !== null) panel.append(remedy)
-      const diagnostics = JSON.stringify({
-        pluginVersion: state.bootstrap?.ok === true ? state.bootstrap.value?.pluginVersion ?? 'unknown' : 'unknown',
-        features: state.features,
-        missing: state.missing,
-      }, null, 2)
+      const diagnostics = buildDiagnostics(state)
       panel.append(el('pre', {
         margin: '0',
         padding: '8px',
@@ -720,6 +775,8 @@ window.__ModuleLoader__.load({
         home: null,
         path: '/',
         draft: '/',
+        /** Case-insensitive substring filter for the current directory. */
+        filter: '',
         listing: null,
         /** `{code, params}` or null; the raw host message is never rendered. */
         error: null,
@@ -933,7 +990,7 @@ window.__ModuleLoader__.load({
         }
         if (state.health.status === 'error') {
           strip.setAttribute('data-wsl-health', 'error')
-          const failure = renderFailureNode(state.health.failure, state.bootstrap)
+          const failure = renderFailureNode(state.health.failure, state.bootstrap, state)
           if (failure !== null) strip.append(failure)
           const retry = el('button', {
             ...BUTTON_STYLE,
@@ -1176,7 +1233,7 @@ window.__ModuleLoader__.load({
           renderDegraded(body, state, close, retryDegraded)
         } else {
           if (state.bootstrapError !== null) {
-            const failure = renderFailureNode(state.bootstrapError, state.bootstrap)
+            const failure = renderFailureNode(state.bootstrapError, state.bootstrap, state)
             if (failure !== null) body.push(failure)
           }
 
@@ -1214,7 +1271,7 @@ window.__ModuleLoader__.load({
           body.push(el('div', { display: 'flex', gap: '8px' }, userField, enter))
 
           if (state.error !== null) {
-            const failure = renderFailureNode(state.error, state.bootstrap)
+            const failure = renderFailureNode(state.error, state.bootstrap, state)
             if (failure !== null) body.push(failure)
           }
 
@@ -1263,15 +1320,45 @@ window.__ModuleLoader__.load({
             border: `1px solid ${T.border}`,
             background: T.layer,
           })
-          const directories = (state.listing?.entries ?? []).filter((entry) => entry.kind === 'directory')
+          const allDirectories = (state.listing?.entries ?? []).filter((entry) => entry.kind === 'directory')
+          // Filtering updates the rendered rows in place instead of repainting the
+          // card: a paint per keystroke replaces the input and steals focus (and
+          // breaks IME composition). The initial paint applies the stored filter.
+          const matchesFilter = (name) => state.filter === ''
+            || name.toLowerCase().includes(state.filter.toLowerCase())
+          const empty = el('div', { fontSize: '12px', color: T.dim, padding: '6px' }, copy('filterEmpty'))
+          empty.style.display = 'none'
+          const applyFilter = () => {
+            let visible = 0
+            for (const node of list.querySelectorAll('[data-wsl-entry]')) {
+              const shown = matchesFilter(node.getAttribute('data-name') ?? '')
+              node.style.display = shown ? 'block' : 'none'
+              if (shown) visible += 1
+            }
+            empty.style.display = visible === 0 ? 'block' : 'none'
+            if (state.filter !== '') empty.setAttribute('data-wsl-filter-empty', '')
+            else empty.removeAttribute('data-wsl-filter-empty')
+          }
+          if (state.listing !== null) {
+            const filter = el('input', FIELD_STYLE)
+            filter.value = state.filter
+            filter.placeholder = copy('filterPlaceholder')
+            filter.setAttribute('data-wsl-filter', '')
+            filter.setAttribute('aria-label', copy('filterLabel'))
+            filter.addEventListener('input', () => {
+              state.filter = filter.value
+              applyFilter()
+            })
+            body.push(filter)
+          }
           if (state.listing === null) {
             list.append(el('div', { fontSize: '12px', color: T.dim, padding: '6px' }, copy('readingDir')))
-          } else if (directories.length === 0) {
+          } else if (allDirectories.length === 0) {
             list.append(el('div', { fontSize: '12px', color: T.dim, padding: '6px' }, copy('noSubdirs')))
           } else {
-            for (const entry of directories) {
+            for (const entry of allDirectories) {
               const item = el('button', {
-                display: 'block',
+                display: matchesFilter(entry.name) ? 'block' : 'none',
                 width: '100%',
                 textAlign: 'left',
                 border: 'none',
@@ -1284,11 +1371,16 @@ window.__ModuleLoader__.load({
                 cursor: 'pointer',
               }, `📁 ${entry.name}`)
               item.type = 'button'
+              item.setAttribute('data-wsl-entry', '')
+              item.setAttribute('data-name', entry.name)
               item.addEventListener('mouseenter', () => { item.style.background = T.hover })
               item.addEventListener('mouseleave', () => { item.style.background = 'transparent' })
               item.addEventListener('click', () => { go(joinLinux(state.path, entry.name)) })
               list.append(item)
             }
+            list.append(empty)
+            if (state.filter !== '') empty.setAttribute('data-wsl-filter-empty', '')
+            applyFilter()
           }
           body.push(list)
           if (typeof state.listing?.hidden === 'number' && state.listing.hidden > 0) {
@@ -1308,8 +1400,19 @@ window.__ModuleLoader__.load({
           }
 
           if (state.error !== null) {
-            const failure = renderFailureNode(state.error, state.bootstrap)
+            const failure = renderFailureNode(state.error, state.bootstrap, state)
             if (failure !== null) body.push(failure)
+            // A failed listing left the operator with an error and no way back to
+            // the directory they were reading. Retrying the same load is safe; a
+            // failed commit is deliberately excluded because it may have created
+            // the workspace before the error.
+            if (state.listing === null && !state.working) {
+              const retryList = el('button', BUTTON_STYLE, copy('retryList'))
+              retryList.type = 'button'
+              retryList.setAttribute('data-wsl-list-retry', '')
+              retryList.addEventListener('click', () => { void load() })
+              body.push(el('div', { display: 'flex', justifyContent: 'flex-start' }, retryList))
+            }
           }
 
           const cancel = el('button', BUTTON_STYLE, copy('cancel'))

package/lib/index.js

@@ -25,7 +25,7 @@ import {
 } from './http-admission.js'
 import { buildVariantPlugins } from './wsl/preset.js'
 import { setLocalSubprocess } from './wsl/host-refs.js'
-import { checkLinuxPath, defaultDistro, defaultWorkspaceUnc, listDistros, listLinuxDir, resolveDistroHome, runWslShell } from './wsl/world.js'
+import { checkLinuxPath, defaultDistro, defaultWorkspaceUnc, listDistros, listLinuxDir, resolveDistroHome, runWslShell, wslMajorVersion } from './wsl/world.js'
 import { joinWslUnc, parseWslUnc, shellQuote, windowsToMntPath } from './wsl/paths.js'
 import { WslRouteError, browserFailure, routeErrorFor } from './route-errors.js'
 import { CHECK_IDS, CHECK_LABELS, CHECK_REMEDIES, DOCS, ERROR_CODES, FEATURE_IDS, FEATURE_LABELS } from './protocol.js'
@@ -506,7 +506,13 @@ const METHODS = {
   health: async ({ distro, username }) => {
     assertDistro(distro)
     assertUser(username)
-    return healthFor({ distro, username, wslPath: routeWslPath })
+    // Host-side: the distribution cannot report its own WSL generation.
+    return healthFor({
+      distro,
+      username,
+      wslPath: routeWslPath,
+      wslVersionProbe: ({ distro: name }) => wslMajorVersion(name, { wslPath: routeWslPath }),
+    })
   },
 
   /**

package/lib/protocol.js

@@ -141,7 +141,7 @@ export const FEATURE_LABELS = deepFreeze({
 })
 
 /** Health-check ids, in display order. */
-export const CHECK_IDS = deepFreeze(['bash', 'python3', 'util-linux', 'getent', 'runner', 'helper', 'nnp'])
+export const CHECK_IDS = deepFreeze(['bash', 'python3', 'util-linux', 'getent', 'runner', 'helper', 'nnp', 'wsl2'])
 
 /** Human-readable check names. */
 export const CHECK_LABELS = deepFreeze({
@@ -152,6 +152,7 @@ export const CHECK_LABELS = deepFreeze({
   runner: { zh: '受限模式 runner', en: 'Confinement runner' },
   helper: { zh: 'dsh-wsl-confine helper', en: 'dsh-wsl-confine helper' },
   nnp: { zh: 'NO_NEW_PRIVS', en: 'NO_NEW_PRIVS' },
+  wsl2: { zh: 'WSL2', en: 'WSL2' },
 })
 
 /** The fix for one failed check, keyed by check id. */
@@ -209,6 +210,11 @@ export const CHECK_REMEDIES = deepFreeze({
     zh: 'setpriv 不支持 --no-new-privs，受限模式不会运行；升级发行版的 util-linux。',
     en: 'setpriv lacks --no-new-privs, so restricted mode refuses to run; upgrade the distribution util-linux.',
   },
+  wsl2: {
+    kind: 'text',
+    zh: 'WSL1 不支持：在 Windows 侧运行 `wsl.exe --set-version <发行版> 2` 升级到 WSL2 后再试。',
+    en: 'WSL1 is unsupported: run `wsl.exe --set-version <distro> 2` on Windows to upgrade it to WSL2 first.',
+  },
 })
 
 /**

package/lib/release-check.js

@@ -0,0 +1,69 @@
+/**
+ * Pure publish-readiness rules.
+ *
+ * The 0.7.0 release learned two preconditions the hard way: an expired npm token
+ * (checked by the caller, not here) and pnpm's `minimumReleaseAge` refusing a
+ * just-published version during `install_bundle`. These rules are pure so the
+ * release runbook and the offline suite can pin them without a registry.
+ * @module dsh-wsl-desktop/release-check
+ */
+
+/**
+ * Compare two dotted numeric versions.
+ * @param {string} a - the left version.
+ * @param {string} b - the right version.
+ * @returns {number} -1, 0 or 1.
+ */
+export function compareVersions(a, b) {
+  const left = String(a).split('.').map((part) => Number.parseInt(part, 10) || 0)
+  const right = String(b).split('.').map((part) => Number.parseInt(part, 10) || 0)
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const difference = (left[index] ?? 0) - (right[index] ?? 0)
+    if (difference !== 0) return difference > 0 ? 1 : -1
+  }
+  return 0
+}
+
+/**
+ * Decide whether a version can be published.
+ * @param {{ target: string, latest: string|null, published?: boolean, localTag?: boolean, remoteTag?: boolean, dirty?: boolean }} input -
+ *   the target and the facts gathered by the caller.
+ * @returns {{ ready: boolean, blockers: string[] }} the verdict.
+ */
+export function classifyPublish({ target, latest, published = false, localTag = false, remoteTag = false, dirty = false }) {
+  const blockers = []
+  if (latest === null || latest === undefined) {
+    blockers.push('the registry latest version is unknown (npm view failed)')
+  } else if (compareVersions(target, latest) <= 0) {
+    blockers.push(`target ${target} is not newer than the registry latest ${latest}`)
+  }
+  if (published === true) blockers.push(`target ${target} is already published`)
+  if (localTag === true) blockers.push(`a local tag v${target} already exists`)
+  if (remoteTag === true) blockers.push(`a remote tag v${target} already exists`)
+  if (dirty === true) blockers.push('the working tree carries tracked changes')
+  return { ready: blockers.length === 0, blockers }
+}
+
+/**
+ * When a freshly published version becomes installable under pnpm's minimum age.
+ * @param {{ publishedAt: string|null, minimumReleaseAgeMinutes: number, now: Date }} input -
+ *   the registry publish time, the configured window and the current time.
+ * @returns {{ ready: boolean|null, readyAt: Date|null, detail: string }} the verdict.
+ */
+export function installWindow({ publishedAt, minimumReleaseAgeMinutes, now = new Date() }) {
+  if (publishedAt === null || publishedAt === undefined || publishedAt === '') {
+    return { ready: null, readyAt: null, detail: 'the registry publish time is unreadable; wait one full window before retrying' }
+  }
+  const published = new Date(publishedAt)
+  if (Number.isNaN(published.getTime()) || !Number.isFinite(minimumReleaseAgeMinutes)) {
+    return { ready: null, readyAt: null, detail: 'the publish time or the minimum age is unreadable' }
+  }
+  const readyAt = new Date(published.getTime() + minimumReleaseAgeMinutes * 60_000)
+  return {
+    ready: now.getTime() >= readyAt.getTime(),
+    readyAt,
+    detail: now.getTime() >= readyAt.getTime()
+      ? 'outside the minimumReleaseAge window'
+      : `inside the minimumReleaseAge window until ${readyAt.toISOString()}`,
+  }
+}

package/lib/wsl/doctor.js

@@ -192,7 +192,7 @@ async function probeHelperVersion({ distro, username, run, wslPath }) {
  * @param {object} options - probe inputs.
  * @returns {Promise<object>} the health answer.
  */
-async function computeHealth({ distro, username, run, wslPath, now, runnerProbe, nnpProbe, helperProbe }) {
+async function computeHealth({ distro, username, run, wslPath, now, runnerProbe, nnpProbe, helperProbe, wslVersionProbe }) {
   // The cached probes call `run` themselves and do not know about the plugin's
   // configured wsl.exe path, so the doctor binds it once for every probe it hands
   // them. Without this they silently fall back to the bare `wsl.exe`.
@@ -206,11 +206,16 @@ async function computeHealth({ distro, username, run, wslPath, now, runnerProbe,
     run: probeRun,
     cacheKey: typeof wslPath === 'string' ? wslPath : '',
   }
-  const [values, runnerOutcome, nnpOutcome] = await Promise.all([
+  const [values, runnerOutcome, nnpOutcome, wslVersionOutcome] = await Promise.all([
     runBatch({ distro, username, run, wslPath }),
     bounded(Promise.resolve().then(() => runnerProbe(probeOptions)), PROBE_RACE_MS),
     bounded(Promise.resolve().then(() => nnpProbe(probeOptions)), PROBE_RACE_MS),
+    // Host-side, not in-distro: a WSL1 distribution's mount-namespace semantics
+    // are not visible from inside it. The route passes a real probe; the suite
+    // injects one, so no new spawn leaks into the existing cases.
+    bounded(Promise.resolve().then(() => wslVersionProbe({ distro, wslPath })), PROBE_RACE_MS),
   ])
+  const wslVersion = wslVersionOutcome?.value ?? null
 
   const measured = Object.keys(values).length > 0
   const family = distroFamily(values)
@@ -290,6 +295,13 @@ async function computeHealth({ distro, username, run, wslPath, now, runnerProbe,
     } else {
       add('nnp', 'unknown', 'unmeasured')
     }
+    if (wslVersion === '1') {
+      add('wsl2', 'fail', 'WSL1 distribution; the mount-namespace boundary needs WSL2')
+    } else if (wslVersion === '2') {
+      add('wsl2', 'pass', 'WSL2')
+    } else {
+      add('wsl2', 'unknown', 'not measured')
+    }
   }
 
   const statusOf = (id) => checks.find((entry) => entry.id === id)?.status
@@ -320,6 +332,7 @@ export async function healthFor({
   runnerProbe = detectRunner,
   nnpProbe = detectNoNewPrivs,
   helperProbe = probeHelperVersion,
+  wslVersionProbe = async () => null,
 }) {
   const key = `${distro}\0${username ?? ''}\0${wslPath ?? ''}`
   const cached = healthCache.get(key)
@@ -328,7 +341,7 @@ export async function healthFor({
   }
   const inflight = healthInflight.get(key)
   if (inflight !== undefined) return inflight
-  const pending = computeHealth({ distro, username, run, wslPath, now, runnerProbe, nnpProbe, helperProbe })
+  const pending = computeHealth({ distro, username, run, wslPath, now, runnerProbe, nnpProbe, helperProbe, wslVersionProbe })
     .then((result) => {
       healthCache.set(key, { at: now(), result })
       // The key carries a browser-supplied user; a page could churn spellings to

package/lib/wsl/world.js

@@ -231,6 +231,59 @@ export async function listDistros({ wslPath = 'wsl.exe' } = {}) {
     .filter((line) => line.length > 0)
 }
 
+/**
+ * The WSL major version of one distribution, from `wsl.exe -l -v`.
+ *
+ * WSL1 is explicitly unsupported (its syscall translation layer has no mount
+ * namespace), but until now nothing in the product asked the host which version a
+ * distribution runs. The output is a table:
+ *
+ *   `  NAME      STATE           VERSION`
+ *   `* debian    Running         2`
+ *
+ * The active marker is optional; the version is the last column. A table that
+ * cannot be parsed answers `null` — an unmeasured fact is not a failure.
+ * @param {string} distro - the distribution name.
+ * @param {{ wslPath?: string }} [options] - the configured `wsl.exe` path.
+ * @returns {Promise<'1'|'2'|null>} the major version, or null when unreadable.
+ */
+export async function wslMajorVersion(distro, { wslPath = 'wsl.exe' } = {}) {
+  let stdout
+  try {
+    ({ stdout } = await execFileAsync(wslPath, ['-l', '-v'], {
+      encoding: 'buffer',
+      timeout: DISCOVERY_TIMEOUT_MS,
+      env: { ...process.env, ...WSL_CHILD_ENV },
+    }))
+  } catch {
+    return null
+  }
+  return parseWslVersionTable(decodeWslOutput(stdout), distro)
+}
+
+/**
+ * Pick one distribution's major version out of a `wsl.exe -l -v` table.
+ *
+ * Kept pure and exported so the table's spacing variants are testable without a
+ * real WSL host. The active marker (`*`) is optional; the last column is VERSION.
+ * @param {unknown} text - the decoded table.
+ * @param {string} distro - the distribution name.
+ * @returns {'1'|'2'|null} the major version, or null when the row is absent.
+ */
+export function parseWslVersionTable(text, distro) {
+  const lines = String(text ?? '').split(/\r?\n/)
+  for (const raw of lines) {
+    const line = raw.replace(/\0/g, '').trim()
+    if (line === '') continue
+    const cells = line.replace(/^\*\s*/, '').split(/\s{2,}|\t/).filter((cell) => cell !== '')
+    if (cells.length < 2) continue
+    if (cells[0] !== distro) continue
+    const version = cells[cells.length - 1]
+    return version === '1' || version === '2' ? version : null
+  }
+  return null
+}
+
 /**
  * The Lxss registry values and the two REG_SZ lines the default-distribution read needs.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-wsl-desktop",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./lib/icon.svg",