dshm-compat 0.1.3 → 0.1.4

package/lib/release.js

@@ -0,0 +1,118 @@
+/**
+ * Generic GitHub Release worker acquisition.
+ *
+ * Some native plugins do not ship a runtime in their npm tarball but publish
+ * per-platform workers as release assets. This module finds a Linux asset,
+ * extracts it, and returns the first AArch64/x86_64 ELF. It is repository
+ * agnostic; no package name is special-cased.
+ *
+ * @module dshm-compat/release
+ */
+import { basename } from 'node:path'
+import { elfArch } from './elf.js'
+import { downloadBuffer } from './fetch.js'
+import { extractTar } from './tar.js'
+import { extractZip } from './zip.js'
+
+const API = 'https://api.github.com'
+
+/** @param {any} report */
+export function githubRepo(report) {
+  if (report?.resolved?.kind === 'github' && typeof report.resolved.name === 'string') {
+    const [owner, repo] = report.resolved.name.split('/')
+    if (owner && repo) return { owner, repo }
+  }
+  const repository = report?.package?.repository
+  const url = typeof repository === 'string' ? repository : repository?.url
+  if (typeof url === 'string') {
+    const match = url.match(/github\.com[/:]([^/]+)\/([^/#?]+)/i)
+    if (match) return { owner: match[1], repo: match[2].replace(/\.git$/i, '') }
+  }
+  const tarball = report?.resolved?.tarballUrl
+  if (typeof tarball === 'string') {
+    const match = tarball.match(/api\.github\.com\/repos\/([^/]+)\/([^/]+)/i)
+    if (match) return { owner: match[1], repo: match[2] }
+  }
+  return undefined
+}
+
+/** @param {string} url @param {AbortSignal} [signal] */
+async function fetchJson(url, signal) {
+  const timeout = AbortSignal.timeout(20000)
+  const combined = signal === undefined ? timeout : AbortSignal.any([signal, timeout])
+  const response = await fetch(url, {
+    signal: combined,
+    headers: { accept: 'application/vnd.github+json', 'user-agent': 'dshm-compat' },
+  })
+  if (!response.ok) throw new Error(`GitHub API ${response.status} for ${url}`)
+  return await response.json()
+}
+
+/** @param {string} owner @param {string} repo @param {AbortSignal} [signal] */
+async function releaseAssets(owner, repo, signal) {
+  try {
+    const latest = await fetchJson(`${API}/repos/${owner}/${repo}/releases/latest`, signal)
+    if (Array.isArray(latest?.assets)) return latest.assets
+  } catch { /* fall through to the list endpoint */ }
+  const releases = await fetchJson(`${API}/repos/${owner}/${repo}/releases?per_page=5`, signal)
+  /** @type {any[]} */
+  const assets = []
+  for (const release of Array.isArray(releases) ? releases : []) {
+    if (Array.isArray(release?.assets)) assets.push(...release.assets)
+  }
+  return assets
+}
+
+/** @param {any} asset */
+function assetRank(asset) {
+  const name = String(asset?.name ?? '').toLowerCase()
+  if (!/\.(?:zip|tgz|tar\.gz)$/.test(name)) return undefined
+  if (/win32|windows|darwin|macos|source|checksum|sha256/.test(name)) return undefined
+  if (!/linux|musl/.test(name)) return undefined
+  if (/aarch64|arm64/.test(name)) return 0
+  if (/x86_64|amd64|x64/.test(name)) return 1
+  return undefined
+}
+
+/** @param {Buffer} archive @param {string} name */
+function archiveEntries(archive, name) {
+  if (/\.zip$/i.test(name)) return extractZip(archive)
+  return extractTar(archive).entries
+    .filter(entry => entry.type === 'file')
+    .map(entry => ({ path: entry.path, data: entry.data }))
+}
+
+/**
+ * @param {any} report
+ * @param {{ signal?: AbortSignal }} [options]
+ * @returns {Promise<{ buffer: Buffer, name: string, arch: 'arm64'|'x64', asset: string } | undefined>}
+ */
+export async function findReleaseWorker(report, options = {}) {
+  const repo = githubRepo(report)
+  if (repo === undefined) return undefined
+  let assets
+  try { assets = await releaseAssets(repo.owner, repo.repo, options.signal) } catch { return undefined }
+  const ranked = assets
+    .map(asset => ({ asset, rank: assetRank(asset) }))
+    .filter(item => item.rank !== undefined)
+    .sort((a, b) => a.rank - b.rank)
+  for (const { asset } of ranked) {
+    if (typeof asset.browser_download_url !== 'string' || Number(asset.size ?? 0) > 64 * 1024 * 1024) continue
+    let archive
+    try { archive = await downloadBuffer(asset.browser_download_url, { maxBytes: 64 * 1024 * 1024, signal: options.signal }) } catch { continue }
+    let entries
+    try { entries = archiveEntries(archive, asset.name) } catch { continue }
+    const candidates = entries
+      .filter(entry => elfArch(entry.data) !== undefined)
+      .sort((a, b) => b.data.length - a.data.length)
+    if (candidates.length === 0) continue
+    const worker = candidates[0]
+    return {
+      buffer: worker.data,
+      name: basename(worker.path),
+      arch: elfArch(worker.data),
+      asset: asset.name,
+    }
+  }
+  return undefined
+}

package/lib/rules.js

@@ -1,9 +1,11 @@
 /**
- * Compatibility rules for known packages.
+ * Custom compatibility rules.
  *
- * Heuristics classify unknown packages. A rule is for a package whose exact
- * blocker and conversion recipe are already known; it wins over the heuristic
- * and carries the build/run instructions the converter cannot infer.
+ * Heuristics classify unknown packages. A rule is an operator-supplied hint for
+ * a package whose exact blocker and conversion recipe are already known; it wins
+ * over the heuristic and carries build/run instructions the converter cannot
+ * infer. Built-in per-package rules are intentionally absent: adaptation lives
+ * in the generic engines, not in a package-name branch.
  *
  * A deployment can add rules in
  * `$DSH_HOME/dshm-compat/registry.json`:
@@ -28,24 +30,7 @@ import { compatDir } from './state.js'
  */
 
 /** @type {Record<string, PackageRule>} */
-export const PACKAGE_RULES = {
-  'dsh-ops': {
-    strategy: 'S2',
-    reason: 'the plugin is a Rust worker executable; the published package carries only win32-x64, linux-x64 and darwin-arm64 payloads',
-    next: [
-      'cross-build native/ for aarch64-unknown-linux-musl',
-      'run dsh-ops-worker in the Alpine guest and proxy the ops_* tools over RPC',
-      'rewrite PLATFORMS, package.json os/cpu and dsh-plugin.json targets for linux-arm64',
-    ],
-    nativeBuild: {
-      language: 'rust',
-      target: 'aarch64-unknown-linux-musl',
-      crate: 'native/Cargo.toml',
-      binary: 'dsh-ops-worker',
-      notes: 'the crate is portable; windows/darwin metadata crates are target-gated',
-    },
-  },
-}
+export const PACKAGE_RULES = {}
 
 const STRATEGIES = new Set(['S0', 'S1', 'S2', 'S3', 'S4'])
 

package/lib/s2-native.js

@@ -0,0 +1,254 @@
+/**
+ * Generic S2 native adapter (dsh-ops is the first fixture).
+ *
+ * A native plugin usually ships a worker plus JS that (a) gates a PLATFORMS
+ * matrix, (b) interpolates `${platform}-${arch}` into runtime paths, and
+ * (c) spawns a worker argv array. This adapter normalizes those three patterns
+ * and stages an externally built AArch64 musl worker. It is package-name
+ * agnostic; dsh-ops remains the reference sample and test fixture.
+ *
+ * @module dshm-compat/s2-native
+ */
+import { createHash } from 'node:crypto'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { analyze } from './analyze.js'
+import { elfArch } from './elf.js'
+import { loadArchive, resolveSpec } from './fetch.js'
+import { packTarGz } from './pack.js'
+import { findReleaseWorker } from './release.js'
+import { compatDir } from './state.js'
+import { extractTar, findRootPrefix } from './tar.js'
+import { validateTarball } from './validate.js'
+
+const BUILD_COMMAND = 'cargo build --release --locked --manifest-path native/Cargo.toml --target aarch64-unknown-linux-musl'
+const TARGET = 'aarch64-unknown-linux-musl'
+const QEMU_ROOT = fileURLToPath(new URL('../assets/qemu-x86_64/', import.meta.url))
+
+/** @param {import('../tar.js').TarEntry[]} entries */
+function selectRoot(entries) {
+  const candidates = entries
+    .filter(entry => entry.type === 'file' && (entry.path === 'package.json' || entry.path.endsWith('/package.json')))
+    .map(entry => ({ dir: entry.path === 'package.json' ? '' : entry.path.slice(0, -'/package.json'.length), depth: entry.path.split('/').length }))
+    .sort((a, b) => a.depth - b.depth)
+  return candidates.length === 0 ? '' : (candidates[0].dir === '' ? '' : `${candidates[0].dir}/`)
+}
+
+/**
+ * @param {string} spec
+ * @param {{ report?: any, workerPath?: string, workerBinary?: Buffer, signal?: AbortSignal }} [options]
+ */
+export async function convertS2Native(spec, options = {}) {
+  const report = options.report ?? await analyze(spec, { textScan: false, signal: options.signal })
+  const packageName = report.package?.name ?? report.resolved?.name ?? 'native-plugin'
+  const packageVersion = report.package?.version ?? report.resolved?.version ?? '0.0.0'
+  const resolved = await resolveSpec(spec, { signal: options.signal })
+  const archive = await loadArchive(resolved, { signal: options.signal })
+  const { entries } = extractTar(archive)
+  const prefix = findRootPrefix(entries)
+  const top = entries
+    .filter(entry => entry.type === 'file')
+    .map(entry => ({ ...entry, path: prefix !== '' && entry.path.startsWith(prefix) ? entry.path.slice(prefix.length) : entry.path }))
+  const root = selectRoot(top)
+  const files = top
+    .filter(entry => entry.path.startsWith(root))
+    .map(entry => ({ ...entry, path: entry.path.slice(root.length) }))
+  const byPath = new Map(files.map(file => [file.path, file]))
+  const getText = path => byPath.get(path)?.data?.toString('utf8')
+
+  let workerBinary = options.workerBinary
+  let workerName = options.workerName
+  if (workerBinary === undefined && typeof options.workerPath === 'string') {
+    try {
+      workerBinary = readFileSync(options.workerPath)
+      workerName ??= basename(options.workerPath)
+    } catch (error) {
+      return { status: 'needs-native-build', target: TARGET, command: BUILD_COMMAND, message: `cannot read worker: ${String(error?.message ?? error)}` }
+    }
+  }
+  if (workerBinary === undefined) {
+    const candidate = files.find(file => file.type === 'file'
+      && /^runtime\/linux-(?:arm64|x64)\//.test(file.path)
+      && !file.path.endsWith('/provenance.json')
+      && elfArch(file.data) !== undefined)
+    if (candidate !== undefined) {
+      workerBinary = candidate.data
+      workerName = basename(candidate.path)
+    }
+  }
+  let acquiredAsset
+  if (workerBinary === undefined) {
+    const releaseWorker = await findReleaseWorker(report, { signal: options.signal })
+    if (releaseWorker !== undefined) {
+      workerBinary = releaseWorker.buffer
+      workerName = releaseWorker.name
+      acquiredAsset = releaseWorker.asset
+    }
+  }
+  if (workerBinary === undefined) {
+    return {
+      status: 'needs-native-build',
+      target: TARGET,
+      command: BUILD_COMMAND,
+      message: `${packageName} needs a Linux arm64 or x64 worker; build one or pass workerPath to compat_convert`,
+      notes: [
+        'install a Rust toolchain and a musl aarch64 cross linker, or use cross/cargo-zigbuild',
+        'stage the result at runtime/linux-arm64/<worker> or runtime/linux-x64/<worker>, or pass it as workerPath',
+      ],
+    }
+  }
+  const workerArch = elfArch(workerBinary)
+  if (workerArch === undefined) {
+    return { status: 'invalid-worker', message: 'worker is not an AArch64 or x86_64 ELF image' }
+  }
+  const runtimeTarget = workerArch === 'arm64' ? 'linux-arm64' : 'linux-x64'
+  workerName ??= 'worker'
+
+  const runtimeEntry = files.find(file => file.type === 'file'
+    && file.path.endsWith('.js')
+    && file.data?.toString('utf8').includes('export const PLATFORMS = Object.freeze(['))
+  if (runtimeEntry === undefined) {
+    return { status: 'recipe-mismatch', message: `${packageName} has no JS file exposing the PLATFORMS matrix` }
+  }
+  const runtime = runtimeEntry.data.toString('utf8')
+  const platformsMatch = runtime.match(/export const PLATFORMS = Object\.freeze\(\[([^\]]*)\]\)/)
+  const platforms = platformsMatch[1]
+    .split(',')
+    .map(item => item.trim().replace(/^['"]|['"]$/g, ''))
+    .filter(item => item !== '')
+  if (!platforms.includes(runtimeTarget)) platforms.push(runtimeTarget)
+  const platformLine = `export const PLATFORMS = Object.freeze([${platforms.map(item => `'${item}'`).join(', ')}])`
+  const targetHelper = "\nconst resolveTarget = (platform, arch) => (platform === 'openharmony' || (platform === 'linux' && arch === 'arm64')) ? '" + runtimeTarget + "' : `${platform}-${arch}`\n"
+  let patchedRuntime = runtime.replaceAll('${platform}-${arch}', '${resolveTarget(platform, arch)}')
+  patchedRuntime = patchedRuntime.replace(platformsMatch[0], `${platformLine}${targetHelper}`)
+  const signature = 'export function resolveWorker(config = {}, { packageRoot = PACKAGE_ROOT, env = process.env, platform = process.platform, arch = process.arch } = {}) {'
+  if (!patchedRuntime.includes(signature)) return { status: 'recipe-mismatch', message: 'resolveWorker signature changed' }
+
+  const patchedSources = new Map()
+  for (const file of files) {
+    if (file.type !== 'file' || !file.path.endsWith('.js') || file.data === undefined) continue
+    let text = file.data.toString('utf8')
+    const before = text
+    text = text
+      .replaceAll('const argv = [file]', "const argv = ['bash', '-c', 'exec \"$0\" \"$@\"', file]")
+      .replaceAll('let argv = [file]', "let argv = ['bash', '-c', 'exec \"$0\" \"$@\"', file]")
+    if (text !== before) patchedSources.set(file.path, text)
+  }
+  if (patchedSources.size === 0) {
+    return { status: 'recipe-mismatch', message: `${packageName} has no standard native worker spawn (const/let argv = [file])` }
+  }
+
+  const pkgFile = byPath.get('package.json')
+  if (pkgFile?.data === undefined) return { status: 'invalid-package', message: 'package.json is missing' }
+  const pkg = JSON.parse(pkgFile.data.toString('utf8'))
+  delete pkg.os
+  delete pkg.cpu
+  // DSHM core is a prerelease (e.g. 0.2.1-alpha.4+dshm.56). The upstream
+  // ^0.2.0-rc.2 range does not match 0.2.1-*, and the bundle loader would throw
+  // on the next boot. "workspace:*" follows the running core instead.
+  if (pkg.peerDependencies !== null && typeof pkg.peerDependencies === 'object' && !Array.isArray(pkg.peerDependencies)) {
+    if (typeof pkg.peerDependencies['@deepseek-ai/dsh'] === 'string') {
+      pkg.peerDependencies['@deepseek-ai/dsh'] = 'workspace:*'
+    }
+  }
+  if (pkg.optionalDependencies !== null && typeof pkg.optionalDependencies === 'object') {
+    for (const name of Object.keys(pkg.optionalDependencies)) {
+      if (/(?:^|[-/])(?:win32|darwin)(?:[-/]|$)/i.test(name)) delete pkg.optionalDependencies[name]
+    }
+  }
+
+  const pluginFile = byPath.get('dsh-plugin.json')
+  if (pluginFile?.data !== undefined) {
+    const manifest = JSON.parse(pluginFile.data.toString('utf8'))
+    const components = manifest?.contributes?.['x-components']
+    if (Array.isArray(components)) {
+      for (const component of components) {
+        if (component === null || typeof component !== 'object') continue
+        if (Array.isArray(component.platforms) && !component.platforms.includes('openharmony')) component.platforms.push('openharmony')
+        if (Array.isArray(component.targets) && !component.targets.includes(runtimeTarget)) component.targets.push(runtimeTarget)
+        if (Array.isArray(component.architectures) && !component.architectures.includes('arm64')) component.architectures.push('arm64')
+      }
+    }
+    pluginFile.data = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+  }
+
+  const runtimeDir = `runtime/${runtimeTarget}`
+  const workerPath = `${runtimeDir}/${workerName}`
+  const provenancePath = `${runtimeDir}/provenance.json`
+  /** @type {{ path: string, data: Buffer, mode?: number }[]} */
+  const extraEntries = []
+  let stagedWorker = workerBinary
+  let workerSource = 'external aarch64-unknown-linux-musl build supplied by the caller'
+  if (workerArch === 'x64') {
+    try {
+      const wrapper = Buffer.from([
+        '#!/bin/sh',
+        'set -e',
+        'DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)',
+        `exec "$DIR/qemu-x86_64" -L "$DIR/rootfs" "$DIR/${workerName}-x64" "$@"`,
+        '',
+      ].join('\n'))
+      stagedWorker = wrapper
+      workerSource = 'x86_64 worker executed through the bundled qemu-x86_64 and glibc rootfs'
+      extraEntries.push({ path: `${runtimeDir}/${workerName}-x64`, data: workerBinary, mode: 0o755 })
+      extraEntries.push({ path: `${runtimeDir}/qemu-x86_64`, data: readFileSync(join(QEMU_ROOT, 'qemu-x86_64')), mode: 0o755 })
+      extraEntries.push({ path: `${runtimeDir}/rootfs/lib64/ld-linux-x86-64.so.2`, data: readFileSync(join(QEMU_ROOT, 'rootfs', 'lib64', 'ld-linux-x86-64.so.2')), mode: 0o644 })
+      extraEntries.push({ path: `${runtimeDir}/rootfs/lib/x86_64-linux-gnu/libc.so.6`, data: readFileSync(join(QEMU_ROOT, 'rootfs', 'lib', 'x86_64-linux-gnu', 'libc.so.6')), mode: 0o644 })
+      extraEntries.push({ path: `${runtimeDir}/rootfs/lib/x86_64-linux-gnu/libgcc_s.so.1`, data: readFileSync(join(QEMU_ROOT, 'rootfs', 'lib', 'x86_64-linux-gnu', 'libgcc_s.so.1')), mode: 0o644 })
+    } catch (error) {
+      return { status: 'invalid-output', error: `cannot stage the bundled qemu runtime: ${String(error?.message ?? error)}` }
+    }
+  }
+  const sha256 = createHash('sha256').update(stagedWorker).digest('hex')
+  const provenance = {
+    version: typeof pkg.version === 'string' ? pkg.version : '0.0.0',
+    target: runtimeTarget,
+    executable: workerName,
+    sha256,
+    source: workerSource,
+  }
+
+  /** @type {string[]} */
+  const changed = [
+    `added ${runtimeTarget} to PLATFORMS and mapped openharmony/arm64 to it`,
+    `wrapped ${patchedSources.size} native worker spawn(s) in bash -c so dshm-vm-bash routes them to the guest`,
+    'removed package.json os/cpu gates and non-Linux optional payloads',
+    'relaxed @deepseek-ai/dsh peer range to workspace:* for the DSHM core',
+    `added dsh-plugin.json openharmony/${runtimeTarget} targets`,
+    ...(acquiredAsset === undefined ? [] : [`acquired ${workerName} from GitHub release asset ${acquiredAsset}`]),
+    workerArch === 'x64'
+      ? `staged ${workerName} as a shell wrapper over qemu-x86_64 + glibc rootfs`
+      : `staged ${workerPath}`,
+  ]
+
+  const output = files.filter(file => file.path !== workerPath).map(file => {
+    if (file.path === runtimeEntry.path) return { path: file.path, data: Buffer.from(patchedRuntime, 'utf8'), mode: file.mode }
+    if (patchedSources.has(file.path)) return { path: file.path, data: Buffer.from(patchedSources.get(file.path), 'utf8'), mode: file.mode }
+    if (file.path === 'package.json') return { path: file.path, data: Buffer.from(`${JSON.stringify(pkg, null, 2)}\n`, 'utf8'), mode: file.mode }
+    return { path: file.path, data: file.data, mode: file.mode }
+  })
+  output.push({ path: workerPath, data: stagedWorker, mode: 0o755 })
+  output.push(...extraEntries)
+  output.push({ path: provenancePath, data: Buffer.from(`${JSON.stringify(provenance, null, 2)}\n`, 'utf8'), mode: 0o644 })
+
+  const packed = packTarGz(output)
+  const outputDir = join(compatDir(process.env), 'builds')
+  mkdirSync(outputDir, { recursive: true })
+  const safeName = String(packageName).replace(/^@/, '').replace(/[\\/]/g, '-').replace(/[^A-Za-z0-9._-]/g, '_')
+  const tarball = join(outputDir, `${safeName}-${pkg.version ?? '0.0.0'}-dshm.tgz`)
+  writeFileSync(tarball, packed)
+  const validation = validateTarball(tarball)
+  if (!validation.ok) return { status: 'invalid-output', tarball, errors: validation.errors }
+  return {
+    status: 'ok',
+    tarball,
+    bytes: packed.length,
+    sha256: createHash('sha256').update(packed).digest('hex'),
+    changed,
+    warnings: validation.warnings,
+    validation,
+    worker: { target: workerArch === 'arm64' ? TARGET : 'x86_64-linux-gnu', arch: workerArch, sha256 },
+  }
+}
+

package/lib/sidecar.js

@@ -0,0 +1,174 @@
+/**
+ * Generic guest sidecar staging and JSON-stdio calls.
+ *
+ * An S2 plugin's native worker is a Linux/AArch64 executable. This module
+ * stages such a worker from a converted tarball into
+ * `$DSH_HOME/dshm-compat/sidecars/<id>/` and invokes it inside the Alpine guest
+ * through the public subprocess service (which `dshm-vm-bash` routes).
+ *
+ * The worker protocol assumed here is one JSON request on stdin and one JSON
+ * value on stdout per process. That is the protocol most native DSH plugins use
+ * and the one the generic S2 adapter's `bash -c` wrapper preserves.
+ *
+ * @module dshm-compat/sidecar
+ */
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { join, posix } from 'node:path'
+import { elfSummary } from './elf.js'
+import { runGuestFile } from './guest.js'
+import { compatDir } from './state.js'
+import { extractTar } from './tar.js'
+
+const ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/i
+
+/** @param {NodeJS.ProcessEnv} env */
+export function sidecarRoot(env = process.env) {
+  return join(compatDir(env), 'sidecars')
+}
+
+/** @param {string} id */
+export function validSidecarId(id) {
+  return typeof id === 'string' && ID_PATTERN.test(id)
+}
+
+/** @param {string} path */
+function safeRelative(path) {
+  if (typeof path !== 'string' || path === '' || path.startsWith('/') || path.includes('\\')) return undefined
+  const normalized = posix.normalize(path).replace(/^\.\//, '')
+  if (normalized.startsWith('../') || normalized === '..') return undefined
+  return normalized
+}
+
+/** @param {NodeJS.ProcessEnv} env @param {string} id */
+export function sidecarDir(id, env = process.env) {
+  if (!validSidecarId(id)) throw Object.assign(new Error('invalid sidecar id'), { code: 'INVALID_ID' })
+  return join(sidecarRoot(env), id)
+}
+
+/** @param {NodeJS.ProcessEnv} env @param {string} id */
+export function readSidecar(id, env = process.env) {
+  try {
+    const meta = JSON.parse(readFileSync(join(sidecarDir(id, env), 'meta.json'), 'utf8'))
+    return meta !== null && typeof meta === 'object' ? meta : undefined
+  } catch { return undefined }
+}
+
+/** @param {NodeJS.ProcessEnv} env */
+export function listSidecars(env = process.env) {
+  const root = sidecarRoot(env)
+  let entries
+  try { entries = readdirSync(root, { withFileTypes: true }) } catch { return [] }
+  const result = []
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const meta = readSidecar(entry.name, env)
+    if (meta !== undefined) result.push(meta)
+  }
+  return result.sort((a, b) => String(a.id).localeCompare(String(b.id)))
+}
+
+/**
+ * Stage a worker file from a tarball.
+ *
+ * @param {string} tarball
+ * @param {string} workerPath - path inside the package, e.g. `runtime/linux-arm64/<worker>`.
+ * @param {{ id?: string, env?: NodeJS.ProcessEnv }} [options]
+ */
+export function stageSidecar(tarball, workerPath, options = {}) {
+  const env = options.env ?? process.env
+  const relative = safeRelative(workerPath)
+  if (relative === undefined) return { ok: false, error: 'workerPath must be a relative path inside the package' }
+  if (typeof tarball !== 'string' || !existsSync(tarball)) return { ok: false, error: `tarball not found: ${String(tarball)}` }
+
+  let entries
+  try { entries = extractTar(readFileSync(tarball)).entries } catch (error) {
+    return { ok: false, error: `cannot read tarball: ${String(error?.message ?? error)}` }
+  }
+  const entry = entries.find(item => item.type === 'file' && item.path === `package/${relative}`)
+  if (entry?.data === undefined) return { ok: false, error: `worker not found in tarball: package/${relative}` }
+  const elf = elfSummary(entry.data)
+  if (elf === undefined) return { ok: false, error: 'worker is not an AArch64 ELF image' }
+
+  const id = options.id ?? `worker-${elf.type.toLowerCase()}`
+  if (!validSidecarId(id)) return { ok: false, error: `invalid sidecar id: ${String(id)}` }
+  const target = sidecarDir(id, env)
+  const staging = `${target}.staging-${process.pid}-${Date.now()}`
+  try {
+    rmSync(staging, { recursive: true, force: true })
+    mkdirSync(staging, { recursive: true })
+    writeFileSync(join(staging, 'worker'), entry.data, { mode: 0o755 })
+    const sha256 = createHash('sha256').update(entry.data).digest('hex')
+    const meta = {
+      id,
+      worker: join(target, 'worker'),
+      workerPath: relative,
+      sha256,
+      bytes: entry.data.length,
+      elf,
+      source: tarball,
+      stagedAt: new Date().toISOString(),
+    }
+    writeFileSync(join(staging, 'meta.json'), `${JSON.stringify(meta, null, 2)}\n`, 'utf8')
+    rmSync(target, { recursive: true, force: true })
+    renameSync(staging, target)
+    return { ok: true, ...meta }
+  } catch (error) {
+    try { rmSync(staging, { recursive: true, force: true }) } catch { /* best effort */ }
+    return { ok: false, error: `cannot stage sidecar: ${String(error?.message ?? error)}` }
+  }
+}
+
+/**
+ * Call a staged worker with one JSON request.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {string} id
+ * @param {unknown} input
+ * @param {{ timeoutMs?: number, signal?: AbortSignal, env?: NodeJS.ProcessEnv }} [options]
+ */
+export async function callSidecar(ctx, id, input, options = {}) {
+  const env = options.env ?? process.env
+  const meta = readSidecar(id, env)
+  if (meta === undefined || typeof meta.worker !== 'string' || !existsSync(meta.worker)) {
+    return { ok: false, error: `sidecar not staged: ${String(id)}` }
+  }
+  const result = await runGuestFile(ctx, meta.worker, [], JSON.stringify(input ?? {}), {
+    timeoutMs: options.timeoutMs ?? 120000,
+    signal: options.signal,
+  })
+  if (result.status !== 'ok') {
+    return { ok: false, status: result.status, error: result.reason ?? `worker exited ${result.exitCode}`, stdout: result.stdout, stderr: result.stderr }
+  }
+  try {
+    return { ok: true, value: JSON.parse(String(result.stdout).trim()), stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode }
+  } catch {
+    return { ok: false, error: 'worker returned invalid JSON', stdout: result.stdout, stderr: result.stderr }
+  }
+}
+
+/**
+ * Ask a staged worker for its version.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {string} id
+ * @param {{ timeoutMs?: number, signal?: AbortSignal, env?: NodeJS.ProcessEnv }} [options]
+ */
+export async function probeSidecar(ctx, id, options = {}) {
+  const env = options.env ?? process.env
+  const meta = readSidecar(id, env)
+  if (meta === undefined || typeof meta.worker !== 'string' || !existsSync(meta.worker)) {
+    return { ok: false, error: `sidecar not staged: ${String(id)}` }
+  }
+  const result = await runGuestFile(ctx, meta.worker, ['--version'], '', {
+    timeoutMs: options.timeoutMs ?? 30000,
+    signal: options.signal,
+  })
+  return {
+    ok: result.status === 'ok',
+    status: result.status,
+    exitCode: result.exitCode,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    error: result.reason,
+  }
+}

package/lib/zip.js

@@ -0,0 +1,59 @@
+/**
+ * Minimal ZIP reader for GitHub release assets.
+ *
+ * Supports stored (0) and deflate (8) entries and the classic EOCD layout.
+ * It intentionally rejects ZIP64 and encrypted archives: release worker
+ * payloads are small, and a missing worker is better than guessing.
+ *
+ * @module dshm-compat/zip
+ */
+import { inflateRawSync } from 'node:zlib'
+
+const EOCD = 0x06054b50
+const CENTRAL = 0x02014b50
+const LOCAL = 0x04034b50
+
+/** @param {Buffer} buffer */
+export function extractZip(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 22) throw new Error('not a ZIP archive')
+  let eocd = -1
+  const start = Math.max(0, buffer.length - 65557)
+  for (let i = buffer.length - 22; i >= start; i--) {
+    if (buffer.readUInt32LE(i) === EOCD) { eocd = i; break }
+  }
+  if (eocd < 0) throw new Error('ZIP end-of-central-directory not found')
+  const count = buffer.readUInt16LE(eocd + 10)
+  const centralOffset = buffer.readUInt32LE(eocd + 16)
+  if (centralOffset === 0xffffffff || count === 0xffff) throw new Error('ZIP64 is not supported')
+
+  /** @type {{ path: string, data: Buffer }[]} */
+  const entries = []
+  let offset = centralOffset
+  for (let index = 0; index < count; index++) {
+    if (offset + 46 > buffer.length || buffer.readUInt32LE(offset) !== CENTRAL) throw new Error('invalid ZIP central directory')
+    const method = buffer.readUInt16LE(offset + 10)
+    const compressedSize = buffer.readUInt32LE(offset + 20)
+    const uncompressedSize = buffer.readUInt32LE(offset + 24)
+    const nameLength = buffer.readUInt16LE(offset + 28)
+    const extraLength = buffer.readUInt16LE(offset + 30)
+    const commentLength = buffer.readUInt16LE(offset + 32)
+    const localOffset = buffer.readUInt32LE(offset + 42)
+    const name = buffer.subarray(offset + 46, offset + 46 + nameLength).toString('utf8')
+    offset += 46 + nameLength + extraLength + commentLength
+    if (name.endsWith('/')) continue
+    const normalized = name.replace(/\\/g, '/').replace(/^\.\//, '')
+    if (normalized.startsWith('/') || normalized.split('/').includes('..')) throw new Error(`unsafe ZIP path: ${name}`)
+    if (localOffset + 30 > buffer.length || buffer.readUInt32LE(localOffset) !== LOCAL) throw new Error(`invalid ZIP local header: ${name}`)
+    const localNameLength = buffer.readUInt16LE(localOffset + 26)
+    const localExtraLength = buffer.readUInt16LE(localOffset + 28)
+    const dataOffset = localOffset + 30 + localNameLength + localExtraLength
+    const compressed = buffer.subarray(dataOffset, dataOffset + compressedSize)
+    let data
+    if (method === 0) data = compressed
+    else if (method === 8) data = inflateRawSync(compressed)
+    else throw new Error(`unsupported ZIP compression method ${method} for ${name}`)
+    if (data.length !== uncompressedSize) throw new Error(`ZIP size mismatch for ${name}`)
+    entries.push({ path: normalized, data })
+  }
+  return entries
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dshm-compat",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Analyze and convert DSH plugins that cannot be installed or run on HarmonyOS DSHM.",
   "type": "module",
   "main": "index.js",
@@ -24,12 +24,14 @@
     "index.js",
     "bin",
     "lib",
+    "assets",
     "cordis.patch.yml",
     "locale/*.json",
     "icon.svg",
     "README.md",
     "INSTALL.md",
     "CHANGELOG.md",
+    "AGENTS.md",
     "docs/*.md"
   ],
   "engines": {