dsh-wsl-desktop 0.7.2 → 0.7.4

package/README.en.md

@@ -157,6 +157,7 @@ These are real boundaries, not a disclaimer list. Each one tells you where to re
 - [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
+- [Upstream defect reports](issues/README.md) — the harness issues filed, their measured evidence, and how the local workarounds relate
 - [Architecture and flow diagrams](docs/diagrams.md) — interactive architecture, sequence and lifecycle diagrams
 
 Three of the linked documents — the distro support matrix, the upstream proposals and the diagram

package/README.md

@@ -130,6 +130,7 @@ plugin_manager install_bundle dsh-wsl-desktop@<version>
 - [发行版支持矩阵](docs/DISTRO-SUPPORT.md) — 哪些发行版验证过，每种缺什么
 - [兼容性与升级](docs/COMPATIBILITY.md) — 插件与桌面的版本关系、升级顺序、回退步骤
 - [上游 API 提案](docs/UPSTREAM-PROPOSALS.md) — 对 harness 上游的两项提案
+- [上游缺陷记录](issues/README.md) — 已上报 harness 的问题、实测证据与本地规避的关系
 - [架构与流程图](docs/diagrams.md) — 可交互的架构、时序与生命周期图
 
 其中三份——发行版支持矩阵、上游 API 提案、架构与流程图索引——**只有中文版**，因为目前没有对应的

package/lib/client.js

@@ -21,8 +21,23 @@ window.__ModuleLoader__.load({
   id: 'dsh-wsl-desktop',
   factory() {
     // MUST stay equal to the host half's Config.routePath default (lib/index.js).
+    /*
+     * Section index. This file is ONE loader module: `window.__ModuleLoader__`
+     * evaluates a single factory, and splitting it across files would need a
+     * loader capability that has not been measured. The boundaries below are
+     * therefore comments, not files — they exist so a reader can hold one
+     * section at a time, and so a future split has its seams already named.
+     *   1. endpoint, trigger geometry and locale
+     *   2. copy, theme and shared node helpers
+     *   3. route calls and failure rendering
+     *   4. the W workspace picker dialog
+     *   5. the companion button and workspace rows
+     *   6. module registration and dispose
+     */
+
     // Nothing derives one from the other: a deployment that mounts the route
     // elsewhere loses the picker silently.
+    // ── 1. endpoint, trigger geometry and locale ─────────────────────────────
     const ENDPOINT = '/wsl-desktop/api'
 
     /**
@@ -102,6 +117,7 @@ window.__ModuleLoader__.load({
      * The catalog is bilingual, so the dialog can render a host failure in the
      * operator's language without a translation build step.
      */
+    // ── 2. copy, theme and shared node helpers ─────────────────────────────
     const LOCALE = typeof navigator !== 'undefined' && /^zh/i.test(String(navigator.language ?? '')) ? 'zh' : 'en'
 
     /**
@@ -316,6 +332,7 @@ window.__ModuleLoader__.load({
      * @param {object|null} envelope - the route's JSON body, when it parsed.
      * @returns {Error} the failure, with `code` and `params` attached.
      */
+    // ── 3. route calls and failure rendering ─────────────────────────────
     function routeFailure(method, status, envelope) {
       const error = new Error(envelope?.error ?? `${method} failed (HTTP ${status})`)
       error.code = typeof envelope?.code === 'string' ? envelope.code : status === 0 ? 'transport' : 'internal'
@@ -733,6 +750,7 @@ window.__ModuleLoader__.load({
      * so lastIndexOf returned -1 and slice(0, -1) gave 'hom'/'tm' — the host
      * listed /tmp while the "up" button navigated to /tm.
      */
+    // ── 4. the W workspace picker dialog ─────────────────────────────
     function parentOf(path) {
       const absolute = path.startsWith('/') ? path : `/${path}`
       const trimmed = absolute.replace(/\/+$/, '')
@@ -1499,6 +1517,7 @@ window.__ModuleLoader__.load({
     }
 
     /** The injected services the picker and its trigger read. */
+    // ── 5. the companion button and workspace rows ─────────────────────────────
     const companion = { button: null, fallback: null, trigger: null, observer: null, scheduled: false, disposed: false }
 
     /** Whether the missing-workspace-source warning was already printed. */
@@ -2053,6 +2072,8 @@ window.__ModuleLoader__.load({
       }
     }
 
+
+    // ── 6. module registration and dispose ─────────────────────────────
     return {
       // `remote.session` is the namespace the create request travels through
       // (see `createBoundSession`); the harness's own client plugins inject it

package/lib/host/http.js

@@ -0,0 +1,110 @@
+/**
+ * The route's HTTP seam: reading a JSON body, answering with one, and deciding
+ * whether a caller may reach the development-token surface.
+ *
+ * Extracted verbatim from `lib/index.js` (C3). Nothing in here is new behaviour;
+ * the move exists so the plugin entry file carries wiring and lifecycle rather
+ * than request plumbing.
+ * @module dsh-wsl-desktop/host/http
+ */
+
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { MAX_BODY_BYTES, DEV_TOKEN_HEADER, tokenMatches } from '../http-admission.js'
+
+/**
+ * The harness home that holds the user preset root.
+ * @returns {string} the resolved `$DSH_HOME`.
+ */
+export function dshHome() {
+  return process.env.DSH_HOME ?? join(homedir(), '.dsh')
+}
+
+/**
+ * Read one JSON request body, bounded.
+ * @param {import('node:http').IncomingMessage} req - the request to drain.
+ * @returns {Promise<{ text: string | null, byteLength: number }>} the body, or null past the ceiling.
+ */
+export async function readJsonBody(req) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.byteLength
+    if (size > MAX_BODY_BYTES) {
+      // Drain the remainder so the refusal is a readable response, not a socket cut.
+      req.resume()
+      return { text: null, byteLength: size }
+    }
+    chunks.push(chunk)
+  }
+  return { text: Buffer.concat(chunks, size).toString('utf8'), byteLength: size }
+}
+
+/**
+ * Answer one request with a JSON envelope and an explicit status.
+ * @param {import('node:http').ServerResponse} res - the response to complete.
+ * @param {number} status - the HTTP status.
+ * @param {{ ok: boolean }} payload - the envelope, success or failure.
+ */
+export function sendJson(res, status, payload) {
+  const body = JSON.stringify(payload)
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': Buffer.byteLength(body),
+    'cache-control': 'no-store',
+  })
+  res.end(body)
+}
+
+/**
+ * Answer with one admission rejection.
+ * @param {import('node:http').ServerResponse} res - the response to complete.
+ * @param {import('../http-admission.js').Rejection} rejection - the refusal.
+ */
+export function sendRejection(res, rejection) {
+  sendJson(res, rejection.status, { ok: false, code: rejection.code, error: rejection.message })
+}
+
+/** Trust surface consumed here; the browser-side connection package owns the full type. */
+export function connectionOf(ctx) {
+  return Reflect.get(ctx, 'connection')
+}
+
+/**
+ * This installation's development token, minted on first use.
+ *
+ * The file is owner-only and lives outside the repository. A web page cannot
+ * read it, which is what keeps the acceptance surface unreachable from a
+ * cross-site request even though the route itself is on loopback.
+ * @returns {Promise<string>} the token.
+ */
+export async function devToken() {
+  const path = join(dshHome(), 'wsl-desktop-dev-token')
+  try {
+    const existing = (await readFile(path, 'utf8')).trim()
+    if (existing.length > 0) return existing
+    // An empty file is unusual — treat it like absent and re-mint below.
+  } catch (error) {
+    // ENOENT = first use. Any other read failure (ACL, AV lock, disk) must
+    // fail loud rather than silently rotate the credential and revoke every
+    // scripted caller.
+    if (error?.code !== 'ENOENT') throw error
+  }
+  const minted = randomBytes(32).toString('hex')
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, `${minted}\n`, { mode: 0o600 })
+  return minted
+}
+
+/**
+ * Whether one request may use the acceptance surface.
+ * @param {import('node:http').IncomingMessage} req - the request.
+ * @param {{ developerTools: boolean }} config - resolved plugin config.
+ * @returns {Promise<boolean>} true for a caller presenting this installation's token.
+ */
+export async function isDeveloperCaller(req, config) {
+  if (config.developerTools !== true) return false
+  return tokenMatches(req.headers[DEV_TOKEN_HEADER], await devToken(), timingSafeEqual)
+}

package/lib/host/presets.js

@@ -0,0 +1,97 @@
+/**
+ * Preset derivation helpers: variant ids, base rows, and the shell-spec seam.
+ *
+ * Extracted verbatim from `lib/index.js` (C3). Only the PURE helpers moved: the
+ * two that materialise and refresh presets stay in the entry file because they
+ * read and write the plugin's module-level state (`presetState`, `currentGeneration`,
+ * `hostCtx`, `hostReady`). Moving those would mean shipping that state or injecting
+ * it, which is a rewrite, not a move — see the plan's "Out of Scope".
+ * @module dsh-wsl-desktop/host/presets
+ */
+
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { dshHome } from './http.js'
+
+/**
+ * The prefix every generated variant id carries.
+ *
+ * Not exported from `index.js` by accident: the same literal is what the route
+ * filters on, so a change here is a wire-visible change.
+ */
+export const GENERATED_PREFIX = 'wsl-'
+
+/**
+ * The stable id for one base preset's WSL variant.
+ * @param {{ id: string }} preset - the resolved base preset.
+ * @returns {string} the variant id.
+ */
+export function variantIdFor(preset) {
+  return preset.id.startsWith(GENERATED_PREFIX) ? preset.id : `${GENERATED_PREFIX}${preset.id}`
+}
+
+/**
+ * Locate the directory a preset was discovered under.
+ *
+ * A preset may name a row by a path relative to its own directory, so the
+ * variant needs that base to rewrite the name to something that still resolves
+ * from where the variant lives.
+ *
+ * Both spellings are historical: the package is `@deepseek-ai/dsh-agent-preset`
+ * (singular — the plural name never existed, so this resolve always threw), and
+ * since the presets moved into profile YAML declarations the package ships no
+ * `presets/<id>/agent.cordis.yml` tree at all. Neither branch is expected to
+ * hit on a current desktop; a base preset that DOES use relative row names
+ * therefore has no resolvable source directory, and `buildVariantPlugins`
+ * leaves the name as it found it. This stays a lookup rather than a guess so
+ * the failure mode is unchanged if a deployment ever ships that tree again.
+ * @param {string} id - preset id.
+ * @returns {string | undefined} the directory, or undefined when it cannot be found.
+ */
+export function sourceDirFor(id) {
+  const local = join(dshHome(), '.agent-presets', id)
+  if (existsSync(join(local, 'agent.cordis.yml'))) return local
+  try {
+    const manifest = fileURLToPath(import.meta.resolve('@deepseek-ai/dsh-agent-preset/package.json'))
+    const shipped = join(dirname(manifest), 'presets', id)
+    if (existsSync(join(shipped, 'agent.cordis.yml'))) return shipped
+  } catch {
+    // A deployment without the preset package leaves relative names as they are.
+  }
+  return undefined
+}
+
+/**
+ * Read a base preset's declared plugin rows as OBJECTS.
+ *
+ * 0.1.7 keeps each declaration's `PresetDefinition` — with `plugins` as entry
+ * objects — in a registry map that is TS-private but reachable in-process
+ * (ctx.get returns the service instance). No YAML parser is needed on this
+ * path; the public readDocument only exposes a re-dumped text form.
+ * @param {object} presets - the agentPresets service.
+ * @param {string} id - base preset id.
+ * @returns {readonly object[] | null} the declared rows, or null when unreachable.
+ */
+export function basePluginsOf(presets, id) {
+  const plugins = presets.definitions?.get?.(id)?.config?.plugins
+  return Array.isArray(plugins) ? plugins : null
+}
+
+/**
+ * Run a shell spec through whichever seam the host exposes, and always hand back a
+ * handle whose `result()` is awaitable.
+ *
+ * 0.1.7 hosts expose `execute`, which resolves with a live handle; older ones have
+ * only `run`, whose settled result carries no `result()` projection. Both selftest
+ * steps used to spell that dual dispatch themselves, and the second one called
+ * `.result()` on `run`'s settled result — a TypeError on exactly the hosts that
+ * branch exists to support. One owner, so the two steps cannot drift again.
+ * @param {object} shell - the realm's shell service.
+ * @param {object} spec - the resolved spec to run.
+ * @returns {Promise<{ result: () => Promise<object> }>} a result()-able handle.
+ */
+export function runShellSpec(shell, spec) {
+  if (typeof shell.execute === 'function') return shell.execute(spec)
+  return shell.run(spec).then((settled) => ({ result: async () => settled }))
+}

package/lib/host/state.js

@@ -0,0 +1,58 @@
+/**
+ * The plugin's module-level state, named and grouped.
+ *
+ * The route dispatcher calls `METHODS` without carrying the plugin's config, so
+ * the context, the configured `wsl.exe` path and the preset lifecycle cannot be
+ * parameters. They were loose module-level `let`s in `lib/index.js` (seven of them,
+ * counting the binding log and its cap); this module gives
+ * each group one owner, so a reader can see what is shared and why.
+ *
+ * Nothing here is a getter/setter pair: the objects are mutable, and every call
+ * site reads a field. That keeps the move mechanical — `hostCtx.get(x)` became
+ * `hostSession.ctx.get(x)`.
+ * @module dsh-wsl-desktop/host/state
+ */
+
+/** The plugin context and the config it was applied with, as route methods see them. */
+export const hostSession = {
+  /** @type {import('@deepseek-ai/cordis').Context | undefined} */
+  ctx: undefined,
+  /** The configured `wsl.exe` path; the default a fresh install runs with. */
+  wslPath: 'wsl.exe',
+  /** Whether the preset registry has been reached; `bootstrap` waits briefly for it. */
+  ready: false,
+}
+
+/** The preset registration lifecycle. */
+export const presetRun = {
+  /** @type {{ status: string } & Record<string, unknown>} */
+  state: { status: 'pending' },
+  /** @type {{ disposed: boolean, disposers: Map<string, Function> } | null} */
+  generation: null,
+  /** Serialises refreshes so boot-time and developer-token calls cannot interleave. */
+  mutex: Promise.resolve(),
+}
+
+/** Most binding decisions kept for inspection. */
+export const BINDING_LOG_LIMIT = 50
+
+/** The bounded record of preset-binding decisions, reported through the route. */
+export const bindingTape = (() => {
+  /** @type {object[]} */
+  const log = []
+  return {
+    log,
+    /**
+     * Record one decision, dropping the oldest past the cap.
+     *
+     * The log is captured by the closure rather than read off `this`: a caller that
+     * destructures the method (`const { record } = bindingTape`) would otherwise get
+     * `TypeError: this.log is undefined` at the first write.
+     * @param {object} entry - the decision to record.
+     */
+    record(entry) {
+      log.push(entry)
+      if (log.length > BINDING_LOG_LIMIT) log.splice(0, log.length - BINDING_LOG_LIMIT)
+    },
+  }
+})()