@herenfor/dsh-wsl 0.0.0-stage → 0.1.0

package/merge.mjs

@@ -0,0 +1,65 @@
+// Pure graph merge for the UI mirror. Kept free of DSH imports so it can be unit-tested.
+import { createHash } from 'node:crypto'
+
+/**
+ * The two Hosts can work together: DSH of the same major.minor (docs/deployment.md). Patch and prerelease may differ;
+ * the setup dialog offers to align them.
+ */
+export const compatibleReleases = (a, b) => {
+  const pa = /^(\d+)\.(\d+)\./.exec(a?.version ?? ''); const pb = /^(\d+)\.(\d+)\./.exec(b?.version ?? '')
+  return !!pa && !!pb && pa[1] === pb[1] && pa[2] === pb[2]
+}
+
+/**
+ * Merge the user rows of a remote graph into the local one. A remote user row replaces a local row of the same id
+ * (one UI for the window: the WSL side wins). Local rows of entries that a WSL plugin's bundle patch switches off
+ * (`remote.disabled`, e.g. DS Bot turns off DSH's general settings shell to hold its seat) leave the page too: the
+ * patch acts on the WSL Host's composition only, and the page must look as it would there.
+ * Every local batch that contained a replaced or dropped row is split into single-row batches for its remaining rows,
+ * because a batch script would register those rows' factories too.
+ * @param local - this Host's graph.
+ * @param remote - { graph, origin, disabled? } from the WSL agent, or undefined.
+ * @param order - orderByModuleGraph from dsh-client-modules.
+ * @returns { graph, mirrored, dropped } where mirrored maps a package id to its remote row and dropped holds the ids of
+ *   local rows left out.
+ */
+export function mergeGraphs(local, remote, order) {
+  const mirrored = new Map()
+  const dropped = new Set()
+  if (remote === undefined) return { graph: local, mirrored, dropped, reason: 'no remote graph yet' }
+  if (!compatibleReleases(local.release, remote.graph.release)) {
+    return { graph: local, mirrored, dropped, reason: `release differs: local ${JSON.stringify(local.release)}, remote ${JSON.stringify(remote.graph.release)}` }
+  }
+  for (const row of remote.graph.entries) if (remote.origin[row.id] === 'user') mirrored.set(row.id, row)
+  const byId = new Map(local.entries.map((row) => [row.id, row]))
+  for (const { name } of remote.disabled ?? []) if (byId.has(name) && !mirrored.has(name)) dropped.add(name)
+  if (mirrored.size === 0 && dropped.size === 0) return { graph: local, mirrored, dropped, reason: 'remote has no user rows' }
+  const gone = (id) => mirrored.has(id) || dropped.has(id)
+  const entries = order([...local.entries.filter((row) => !gone(row.id)), ...mirrored.values()])
+  const batches = []
+  for (const batch of local.batches) {
+    if (!batch.entries.some(gone)) { batches.push(batch); continue }
+    for (const id of batch.entries) {
+      if (gone(id)) continue
+      const row = byId.get(id)
+      batches.push({ phase: batch.phase, url: row.url, rev: row.rev, entries: [id] })
+    }
+  }
+  for (const row of mirrored.values()) batches.push({ phase: 'application', url: row.url, rev: row.rev, entries: [row.id] })
+  const rev = createHash('sha256').update(JSON.stringify({ entries, batches })).digest('base64url').slice(0, 12)
+  return { graph: { rev, release: local.release, entries, batches }, mirrored, dropped }
+}
+
+/**
+ * The package ids a /plugins request addresses: every id of a combo (`/plugins/??a/client.js,b/client.js&rev=`),
+ * or the package of a chunk or asset path (`/plugins/<id>/...`, scoped ids included).
+ */
+export function requestedPackages(url) {
+  const { pathname, search } = new URL(url, 'http://x')
+  if (search.startsWith('??')) {
+    const list = search.slice(2).split('&')[0]
+    return list.split(',').map((file) => file.replace(/\/client\.js(\.map)?$/, ''))
+  }
+  const parts = pathname.replace(/^\/plugins\//, '').split('/')
+  return [parts[0].startsWith('@') ? `${parts[0]}/${parts[1]}` : parts[0]]
+}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@herenfor/dsh-wsl",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "WSL run mode for DeepSeek Harness Desktop on Windows: run chosen tasks, and the plugins they use, in WSL from the Desktop window",
+  "license": "MIT",
+  "icon": "./icon.svg",
+  "type": "module",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dsh-plugin",
+    "wsl"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/herenfor/dsh-wsl.git",
+    "directory": "experiments/mirror/mirror"
+  },
+  "homepage": "https://github.com/herenfor/dsh-wsl#readme",
+  "bugs": {
+    "url": "https://github.com/herenfor/dsh-wsl/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "dsh": ">=0.2.0-0 <0.3.0-0"
+  },
+  "exports": {
+    ".": "./index.mjs",
+    "./client": "./client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-plugin-manager",
+        "@deepseek-ai/dsh-client-ui-workspace",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    },
+    "manifestVersion": 1
+  },
+  "files": [
+    "*.mjs",
+    "client.js",
+    "cordis.patch.yml",
+    "icon.svg",
+    "locale/*.json",
+    "README.zh.md",
+    "transport/",
+    "agent/"
+  ]
+}

package/paths.mjs

@@ -0,0 +1,24 @@
+// Local-directory install specs between Windows and WSL. A spec may carry pnpm's `file:` or `link:` prefix.
+// Kept free of DSH imports so it can be unit-tested.
+
+const split = (spec) => { const m = /^(file:|link:)?(.*)$/s.exec(spec); return [m[1] ?? '', m[2]] }
+
+/** A Windows path (C:\..., \\wsl.localhost\<distro>\..., \\wsl$\<distro>\...) as WSL sees it; other specs unchanged. */
+export function toWslSpec(spec) {
+  const [prefix, path] = split(spec.trim())
+  const drive = /^([A-Za-z]):[\\/](.*)$/s.exec(path)
+  if (drive) return `${prefix}/mnt/${drive[1].toLowerCase()}/${drive[2].replace(/\\/g, '/')}`.replace(/\/+$/, '')
+  const unc = /^[\\/]{2}(?:wsl\.localhost|wsl\$)[\\/][^\\/]+[\\/]?(.*)$/is.exec(path)
+  if (unc) return `${prefix}/${unc[1].replace(/\\/g, '/')}`.replace(/\/+$/, '') || `${prefix}/`
+  return spec
+}
+
+/** A WSL path as Windows sees it (/mnt/c/... → C:\..., /home/... → \\wsl.localhost\<distro>\home\...); other specs unchanged. */
+export function toWindowsSpec(spec, distro) {
+  const [prefix, path] = split(spec.trim())
+  if (!path.startsWith('/')) return spec
+  const mnt = /^\/mnt\/([a-z])(?:\/(.*))?$/s.exec(path)
+  if (mnt) return `${prefix}${mnt[1].toUpperCase()}:\\${(mnt[2] ?? '').replace(/\//g, '\\')}`
+  if (!distro) return spec
+  return `${prefix}\\\\wsl.localhost\\${distro}${path.replace(/\//g, '\\')}`
+}

package/plugins.mjs

@@ -0,0 +1,77 @@
+// The WSL tab of the Plugins page: which of the WSL Host's bundles it lists, and what it shows of each. The official
+// Installed tab is left to this Host alone. Kept free of DSH imports so it can be unit-tested.
+
+// Bundles the WSL side needs to be reached at all: listed nowhere, so they cannot be switched off from the page.
+const INTERNAL = new Set(['dsh-wsl-agent'])
+
+// Package text as the manifest gives it (a string, or translations by lowercase locale with English among them); the
+// page resolves it in the active language. A map without English gets one, so the page's resolver always has it.
+const text = (value, fallback) => {
+  if (typeof value === 'string') return value
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value).filter(([, v]) => typeof v === 'string')
+    if (entries.length) return { en: value.en ?? entries[0][1], ...Object.fromEntries(entries) }
+  }
+  return fallback
+}
+
+/**
+ * The rows of the WSL tab, as the official Installed tab picks them: the official optional bundles and the installed
+ * ones (the profile's own base bundles are neither), installed ones first.
+ */
+export function wslBundles(bundles) {
+  return bundles
+    .filter((b) => !INTERNAL.has(b.name) && (b.official || b.installed))
+    .map((b) => ({
+      name: b.name,
+      title: text(b.meta?.title, b.name),
+      description: text(b.meta?.description ?? b.description, ''),
+      icon: typeof b.meta?.icon === 'string' ? b.meta.icon : undefined,
+      version: b.version ?? null,
+      official: !!b.official,
+      installed: !!b.installed,
+      enabled: !!b.enabled,
+      availability: b.availability,
+      ...(b.error ? { error: b.error.message ?? String(b.error.code ?? b.error) } : {}),
+    }))
+    .sort((a, b) => Number(a.official) - Number(b.official))
+}
+
+// Official bundles the official page marks as experimental (its own list, by name).
+const EXPERIMENTAL = /^@deepseek-ai\/dsh-(experimental-|cua-bundle$|personalized-recommendations$)/
+
+/**
+ * One bundle's page in the WSL tab, as the official bundle page shows it: the bundle with its rows joined to the
+ * WSL Host's live entries (`listPlugins`).
+ * @returns undefined when the WSL Host lists no such bundle, or one the tab does not list.
+ */
+export function wslBundlePage(bundles, plugins, name) {
+  const bundle = bundles.find((b) => b.name === name)
+  if (bundle === undefined || INTERNAL.has(name)) return undefined
+  const [card] = wslBundles([bundle])
+  if (card === undefined) return undefined
+  const rows = (bundle.rows ?? []).map((row) => {
+    const live = row.entryId === undefined ? undefined : plugins.find((p) => p.entryId === row.entryId)
+    return {
+      rowId: row.rowId,
+      moduleName: row.moduleName,
+      title: text(row.meta?.title, row.rowId),
+      description: text(row.meta?.description, ''),
+      icon: typeof row.meta?.icon === 'string' ? row.meta.icon : undefined,
+      enabled: live?.enabled ?? false,
+      phase: live?.fiberPhase ?? null,
+      ...(live?.diagnostic ? { diagnostic: live.diagnostic } : {}),
+      ...(row.entryId !== undefined ? { entryId: row.entryId } : {}),
+      // The official page locks a row the Host cannot address through the profile patch.
+      locked: row.entryId === undefined || live?.readOnlyReason !== undefined,
+    }
+  })
+  return {
+    ...card,
+    experimental: card.official && EXPERIMENTAL.test(name),
+    removable: !!bundle.removable && !card.official,
+    ...(bundle.source ? { source: bundle.source } : {}),
+    ...(bundle.readOnlyReason ? { readOnly: true } : {}),
+    rows,
+  }
+}

package/remote-mux.mjs

@@ -0,0 +1,154 @@
+// Streams on the WSL DSH Host: one WebSocket to its /api/remote.mux (DSH's JSON text mux), opened over the bridge.
+// A minimal WebSocket client (RFC 6455, text frames, no extensions) so nothing depends on where the Desktop install
+// keeps the `ws` package.
+import { randomBytes, randomUUID, createHash } from 'node:crypto'
+
+const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
+
+/** Error of a remote stream, in the form DSH's gateway passes to the page unchanged. */
+export const remoteError = (failure) => Object.assign(new Error(failure?.message || 'WSL stream failed'), {
+  isDSHRemoteError: true, code: failure?.code || 'internal', details: failure?.details ?? {},
+})
+const carrierError = (message) => remoteError({ code: 'gateway/carrier', message })
+
+function encode(opcode, payload) {
+  const len = payload.length
+  const head = len < 126 ? Buffer.from([0x80 | opcode, 0x80 | len])
+    : len < 65536 ? Buffer.from([0x80 | opcode, 0x80 | 126, len >> 8, len & 255])
+      : (() => { const b = Buffer.alloc(10); b[0] = 0x80 | opcode; b[1] = 0x80 | 127; b.writeBigUInt64BE(BigInt(len), 2); return b })()
+  const mask = randomBytes(4)
+  const body = Buffer.alloc(len)
+  for (let i = 0; i < len; i++) body[i] = payload[i] ^ mask[i & 3]
+  return Buffer.concat([head, mask, body])
+}
+
+class Socket {
+  constructor(socket, head, onText, onClose) {
+    this.socket = socket
+    this.buffer = head?.length ? Buffer.from(head) : Buffer.alloc(0)
+    this.fragments = []
+    this.open = true
+    socket.on('data', (chunk) => { this.buffer = Buffer.concat([this.buffer, chunk]); this.drain(onText) })
+    const closed = () => { if (!this.open) return; this.open = false; onClose() }
+    socket.once('close', closed)
+    socket.once('error', closed)
+    if (this.buffer.length) queueMicrotask(() => this.drain(onText))
+  }
+  drain(onText) {
+    for (;;) {
+      const b = this.buffer
+      if (b.length < 2) return
+      const fin = (b[0] & 0x80) !== 0
+      const opcode = b[0] & 0x0f
+      const masked = (b[1] & 0x80) !== 0
+      let len = b[1] & 0x7f
+      let offset = 2
+      if (len === 126) { if (b.length < 4) return; len = b.readUInt16BE(2); offset = 4 } else if (len === 127) { if (b.length < 10) return; len = Number(b.readBigUInt64BE(2)); offset = 10 }
+      const maskAt = offset
+      if (masked) offset += 4
+      if (b.length < offset + len) return
+      let payload = b.subarray(offset, offset + len)
+      if (masked) { const m = b.subarray(maskAt, maskAt + 4); payload = Buffer.from(payload.map((x, i) => x ^ m[i & 3])) }
+      this.buffer = b.subarray(offset + len)
+      if (opcode === 0x9) this.write(0xa, payload)
+      else if (opcode === 0x8) { this.write(0x8, Buffer.alloc(0)); this.socket.end(); return }
+      else if (opcode === 0x1 || opcode === 0x0) {
+        this.fragments.push(Buffer.from(payload))
+        if (fin) { const text = Buffer.concat(this.fragments).toString('utf8'); this.fragments = []; onText(text) }
+      }
+    }
+  }
+  write(opcode, payload) { if (this.open && !this.socket.destroyed) this.socket.write(encode(opcode, payload)) }
+  send(text) { this.write(0x1, Buffer.from(text, 'utf8')) }
+  close() { if (this.open) { this.write(0x8, Buffer.alloc(0)); this.socket.end() } this.socket.destroy() }
+}
+
+/**
+ * @param upgrade - async () => ({ socket, head }): performs the HTTP upgrade to /api/remote.mux on the WSL Host.
+ */
+export class WslMux {
+  constructor(upgrade) {
+    this.upgrade = upgrade
+    this.streams = new Map()
+  }
+  connect() {
+    if (this.socket?.open) return Promise.resolve()
+    return (this.connecting ??= (async () => {
+      const { socket, head } = await this.upgrade()
+      this.socket = new Socket(socket, head, (text) => this.receive(text), () => {
+        this.socket = undefined
+        for (const inbox of this.streams.values()) inbox.fail(carrierError('The connection to the WSL Host closed.'))
+      })
+    })().finally(() => { this.connecting = undefined }))
+  }
+  receive(text) {
+    let frame
+    try { frame = JSON.parse(text) } catch { return }
+    this.streams.get(frame.streamId)?.push(frame)
+  }
+  /** Open one stream on the WSL Host; yields its items, throws its error. */
+  async *open(endpoint, payload, signal, uplink) {
+    await this.connect()
+    signal?.throwIfAborted()
+    const id = randomUUID()
+    const inbox = new Inbox()
+    this.streams.set(id, inbox)
+    const socket = this.socket
+    const send = (frame) => socket.send(JSON.stringify({ streamId: id, ...frame }))
+    const abort = () => inbox.fail(signal.reason ?? new Error('aborted'))
+    signal?.addEventListener('abort', abort, { once: true })
+    send({ type: 'open', endpoint, payload })
+    let stopped = false
+    let iterator
+    if (uplink) {
+      iterator = uplink[Symbol.asyncIterator]()
+      void (async () => {
+        while (!stopped) {
+          const item = await iterator.next()
+          if (stopped) break
+          if (item.done) { send({ type: 'end' }); break }
+          send({ type: 'item', value: item.value })
+        }
+      })().catch((error) => inbox.fail(error))
+    }
+    let finished = false
+    try {
+      for (;;) {
+        const frame = await inbox.next()
+        if (frame.type === 'item') yield frame.value
+        else if (frame.type === 'error') { finished = true; throw remoteError(frame.error) }
+        else { finished = true; return }
+      }
+    } finally {
+      stopped = true
+      signal?.removeEventListener('abort', abort)
+      if (!finished && socket.open) send({ type: 'cancel' })
+      this.streams.delete(id)
+      void iterator?.return?.()
+    }
+  }
+  close() { this.socket?.close() }
+}
+
+class Inbox {
+  frames = [];
+  push(frame) { this.frames.push(frame); this.wake?.() }
+  fail(error) { this.error ??= error; this.wake?.() }
+  async next() {
+    while (!this.frames.length) {
+      if (this.error) throw this.error
+      await new Promise((resolve) => { this.wake = resolve })
+      this.wake = undefined
+    }
+    return this.frames.shift()
+  }
+}
+
+/** The headers and accept check of a client WebSocket upgrade. */
+export function upgradeHeaders() {
+  const key = randomBytes(16).toString('base64')
+  return {
+    headers: { connection: 'Upgrade', upgrade: 'websocket', 'sec-websocket-version': '13', 'sec-websocket-key': key },
+    accept: createHash('sha1').update(key + GUID).digest('base64'),
+  }
+}

package/routes.mjs

@@ -0,0 +1,47 @@
+// Which WSL Host routes the Desktop Host forwards. Kept free of DSH imports so it can be unit-tested.
+
+// Paths DSH itself owns on every Host; never forwarded even when only the WSL Host has them.
+const RESERVED = [/^\/$/, /^\/api(\/|$)/, /^\/plugins(\/|$)/, /^\/connect$/, /^\/wsl-bridge(\/|$)/, /^\/assets(\/|$)/]
+export const isReserved = (path) => RESERVED.some((re) => re.test(path))
+
+/**
+ * Routes the WSL Host serves and the local Host does not: with the same DSH version and the same official bundles
+ * on both sides, these are the routes of plugins installed only in WSL.
+ * @param remote - { exact: string[], prefix: string[] } from the WSL agent.
+ * @param local - { exact: Set|string[], prefix: Set|string[] } of this Host, without the routes the mirror added.
+ * @returns [{ kind, path }] in a stable order.
+ */
+export function routesToForward(remote, local) {
+  const out = []
+  for (const kind of ['exact', 'prefix']) {
+    const mine = new Set(local?.[kind] ?? [])
+    for (const path of [...(remote?.[kind] ?? [])].sort()) if (!mine.has(path) && !isReserved(path)) out.push({ kind, path })
+  }
+  return out
+}
+
+// Request headers passed to the WSL Host; cookie, host and origin are replaced with the WSL Host's own.
+export const FORWARD_REQUEST_HEADERS = ['accept', 'accept-language', 'content-type', 'cache-control', 'if-none-match', 'if-modified-since', 'last-event-id', 'range']
+// Response headers passed back; set-cookie is dropped so the WSL Host's cookie never reaches the page.
+export const DROP_RESPONSE_HEADERS = new Set(['set-cookie', 'connection', 'keep-alive', 'transfer-encoding', 'content-encoding', 'content-length'])
+
+export const isJson = (type) => typeof type === 'string' && /^application\/(?:[\w.+-]*\+)?json\b/i.test(type.trim())
+
+/**
+ * A chunk rewriter for a Server-Sent Events body: each `data:` line holding JSON goes through `map`. Lines are cut at
+ * line ends, so a partial line waits for the next chunk.
+ */
+export function eventStreamRewriter(map) {
+  const decoder = new TextDecoder()
+  let pending = ''
+  return (chunk) => {
+    pending += decoder.decode(chunk, { stream: true })
+    const end = pending.lastIndexOf('\n')
+    if (end < 0) return Buffer.alloc(0)
+    const lines = pending.slice(0, end + 1)
+    pending = pending.slice(end + 1)
+    return Buffer.from(lines.replace(/^data:( ?)(.*)$/gm, (line, space, data) => {
+      try { return `data:${space}${JSON.stringify(map(JSON.parse(data)))}` } catch { return line }
+    }))
+  }
+}