dshm-compat 0.1.3 → 0.1.5

package/lib/s2-native.js

@@ -0,0 +1,316 @@
+/**
+ * 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')
+
+  const manifestEntry = byPath.get('package.json')
+  let manifest
+  try { manifest = manifestEntry?.data === undefined ? undefined : JSON.parse(manifestEntry.data.toString('utf8')) } catch { manifest = undefined }
+  const main = typeof manifest?.main === 'string' ? manifest.main.replace(/^\.\//, '') : undefined
+  const hasMain = main !== undefined && files.some(file => file.path === main)
+  const buildScript = typeof manifest?.scripts?.build === 'string'
+    ? manifest.scripts.build
+    : typeof manifest?.scripts?.prepack === 'string' ? manifest.scripts.prepack : undefined
+  if (!hasMain && buildScript !== undefined) {
+    return {
+      status: 'needs-build',
+      sourcePackage: true,
+      message: `${packageName} is a source package (main ${main ?? '<missing>'} is absent, build script ${JSON.stringify(buildScript)}); build it outside DSHM, then pass the produced tarball to compat_convert`,
+      build: {
+        command: 'npm ci && npm run build && npm pack',
+        output: 'the produced .tgz',
+        then: 'compat_convert { spec: "<produced.tgz>" }',
+      },
+    }
+  }
+
+  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
+  let acquisition
+  if (workerBinary === undefined) {
+    acquisition = await findReleaseWorker(report, { signal: options.signal })
+    if (acquisition.ok === true) {
+      workerBinary = acquisition.buffer
+      workerName = acquisition.name
+      acquiredAsset = acquisition.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',
+      ],
+      ...(acquisition === undefined ? {} : { acquisition }),
+    }
+  }
+  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) {
+    const manifestEntry = byPath.get('package.json')
+    let manifest
+    try { manifest = manifestEntry?.data === undefined ? undefined : JSON.parse(manifestEntry.data.toString('utf8')) } catch { manifest = undefined }
+    const main = typeof manifest?.main === 'string' ? manifest.main.replace(/^\.\//, '') : undefined
+    const hasMain = main !== undefined && files.some(file => file.path === main)
+    const buildScript = typeof manifest?.scripts?.build === 'string'
+      ? manifest.scripts.build
+      : typeof manifest?.scripts?.prepack === 'string' ? manifest.scripts.prepack : undefined
+    if (!hasMain && buildScript !== undefined) {
+      return {
+        status: 'needs-build',
+        sourcePackage: true,
+        message: `${packageName} is a source package (main ${main ?? '<missing>'} is absent, build script ${JSON.stringify(buildScript)}); build it outside DSHM, then pass the produced tarball to compat_convert`,
+        build: {
+          command: 'npm ci && npm run build && npm pack',
+          output: 'the produced .tgz',
+          then: 'compat_convert { spec: "<produced.tgz>" }',
+        },
+      }
+    }
+    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', file]")
+      .replaceAll('let argv = [file]', "let argv = ['bash', file]")
+      .replaceAll("[file, '-c', command]", "['bash', '-c', command]")
+      .replaceAll('[file, scriptPath]', "['bash', scriptPath]")
+    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
+  if (pkg.engines !== null && typeof pkg.engines === 'object' && !Array.isArray(pkg.engines)) {
+    delete pkg.engines.dsh
+    if (Object.keys(pkg.engines).length === 0) delete pkg.engines
+  }
+  // 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
+  let workerSource
+  try {
+    if (workerArch === 'x64') {
+      const realName = `${workerName}-x64`
+      stagedWorker = Buffer.from([
+        '#!/bin/sh',
+        'set -e',
+        'DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)',
+        `exec "$DIR/qemu-x86_64" -L "$DIR/rootfs" "$DIR/${realName}" "$@"`,
+        '',
+      ].join('\n'))
+      workerSource = 'x86_64 worker executed through the bundled qemu-x86_64 and glibc rootfs'
+      extraEntries.push({ path: `${runtimeDir}/${realName}`, 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 })
+    } else {
+      const realName = `${workerName}-bin`
+      stagedWorker = Buffer.from([
+        '#!/bin/sh',
+        'set -e',
+        'DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)',
+        `exec "$DIR/${realName}" "$@"`,
+        '',
+      ].join('\n'))
+      workerSource = 'external aarch64-unknown-linux-musl build supplied by the caller'
+      extraEntries.push({ path: `${runtimeDir}/${realName}`, data: workerBinary, mode: 0o755 })
+    }
+  } catch (error) {
+    return { status: 'invalid-output', error: `cannot stage the native worker wrapper: ${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`,
+    `rewrote ${patchedSources.size} native worker spawn(s) to ['bash', file] so dshm-vm-bash preserves argv`,
+    'removed package.json os/cpu gates and non-Linux optional payloads',
+    'removed engines.dsh when present so the DSHM bundle loader does not reject the prerelease core',
+    '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 ${workerName} as a shell wrapper over ${workerName}-bin`,
+  ]
+
+  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 },
+    ...(acquisition?.ok === true ? { acquisition: { asset: acquisition.asset, sha256: acquisition.sha256 } } : {}),
+  }
+}
+

package/lib/sidecar.js

@@ -0,0 +1,185 @@
+/**
+ * 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 script = [
+      '#!/bin/sh',
+      'set -e',
+      'DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)',
+      'exec "$DIR/worker" "$@"',
+      '',
+    ].join('\n')
+    writeFileSync(join(staging, 'worker.sh'), script, { mode: 0o755 })
+    const sha256 = createHash('sha256').update(entry.data).digest('hex')
+    const meta = {
+      id,
+      worker: join(target, 'worker'),
+      script: join(target, 'worker.sh'),
+      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 file = typeof meta.script === 'string' ? meta.script : meta.worker
+  const result = await runGuestFile(ctx, file, [], 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 file = typeof meta.script === 'string' ? meta.script : meta.worker
+  const result = await runGuestFile(ctx, file, ['--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/source-build.js

@@ -0,0 +1,165 @@
+/**
+ * Best-effort source build orchestration.
+ *
+ * This is deliberately opt-in. The reliable route for a source-only plugin is
+ * an external build (PC/CI); this module only attempts the same commands inside
+ * the Alpine guest after provisioning a toolchain, and reports the exact
+ * failure when the guest cannot do it.
+ *
+ * @module dshm-compat/source-build
+ */
+import { createHash } from 'node:crypto'
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { loadArchive, resolveSpec } from './fetch.js'
+import { provisionGuest, runGuest } from './guest.js'
+import { compatDir } from './state.js'
+import { extractTar, findRootPrefix } from './tar.js'
+
+/** @param {unknown} value */
+function record(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined
+}
+
+/** @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} value */
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+
+/**
+ * Detect a generic build plan from package files.
+ * @param {{ path: string, data?: Buffer }[]} files
+ */
+export function detectSourceBuild(files) {
+  const byPath = new Map(files.map(file => [file.path, file]))
+  const text = path => byPath.get(path)?.data?.toString('utf8')
+  const cargoPath = ['native/Cargo.toml', 'Cargo.toml'].find(path => byPath.has(path))
+  if (cargoPath !== undefined) {
+    const cargo = text(cargoPath) ?? ''
+    const packageName = cargo.match(/^\s*name\s*=\s*"([^"]+)"/m)?.[1]
+    const binName = cargo.match(/\[\[bin\]\][\s\S]*?^\s*name\s*=\s*"([^"]+)"/m)?.[1]
+    const binary = binName ?? packageName ?? 'worker'
+    return {
+      kind: 'rust',
+      manifest: cargoPath,
+      binary,
+      command: 'cargo build --release',
+      output: `target/release/${binary}`,
+      packages: ['rust', 'cargo', 'build-base', 'linux-headers'],
+      artifact: 'worker',
+    }
+  }
+  const packageText = text('package.json')
+  if (packageText !== undefined) {
+    let pkg
+    try { pkg = JSON.parse(packageText) } catch { pkg = undefined }
+    const build = typeof pkg?.scripts?.build === 'string' ? pkg.scripts.build : typeof pkg?.scripts?.prepack === 'string' ? pkg.scripts.prepack : undefined
+    if (build !== undefined) {
+      const install = byPath.has('package-lock.json') || byPath.has('npm-shrinkwrap.json') ? 'npm ci' : 'npm install'
+      return {
+        kind: 'node',
+        manifest: 'package.json',
+        command: `${install} && npm run build && npm pack`,
+        output: '*.tgz',
+        packages: ['nodejs', 'npm', 'python3', 'build-base', 'linux-headers', 'git'],
+        artifact: 'tarball',
+      }
+    }
+  }
+  return undefined
+}
+
+/**
+ * @param {string} spec
+ * @param {{ env?: NodeJS.ProcessEnv, signal?: AbortSignal }} [options]
+ */
+export async function prepareSource(spec, options = {}) {
+  const env = options.env ?? process.env
+  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 plan = detectSourceBuild(files)
+  if (plan === undefined) return { ok: false, error: 'no generic build plan (Cargo.toml or package.json build/prepack)' }
+
+  const safe = String(resolved.name ?? 'source').replace(/^@/, '').replace(/[\\/]/g, '-').replace(/[^A-Za-z0-9._-]/g, '_')
+  const fingerprint = createHash('sha256').update(`${resolved.name ?? ''}@${resolved.version ?? ''}`).digest('hex').slice(0, 12)
+  const dir = join(compatDir(env), 'builds', 'source', `${safe}-${fingerprint}`)
+  rmSync(dir, { recursive: true, force: true })
+  for (const file of files) {
+    if (file.data === undefined) continue
+    const target = join(dir, ...file.path.split('/'))
+    mkdirSync(join(target, '..'), { recursive: true })
+    writeFileSync(target, file.data, { mode: file.mode & 0o777 })
+  }
+  return { ok: true, dir, plan, packageName: resolved.name, version: resolved.version }
+}
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {string} spec
+ * @param {{ backend?: 'plan'|'guest', env?: NodeJS.ProcessEnv, signal?: AbortSignal, timeoutMs?: number }} [options]
+ */
+export async function buildSource(ctx, spec, options = {}) {
+  const prepared = await prepareSource(spec, options)
+  if (prepared.ok !== true) return { status: 'unsupported', ...prepared }
+  const { dir, plan } = prepared
+  const base = {
+    status: 'planned',
+    source: { name: prepared.packageName, version: prepared.version },
+    directory: dir,
+    plan: {
+      kind: plan.kind,
+      commands: plan.command,
+      output: plan.output,
+      packages: plan.packages,
+    },
+  }
+  if (options.backend !== 'guest') {
+    return { ...base, message: 'run this plan on a PC/CI, or pass backend:"guest" to attempt it in the Alpine guest' }
+  }
+
+  const provision = await provisionGuest(ctx, plan.packages, { timeoutMs: options.timeoutMs ?? 15 * 60 * 1000, signal: options.signal })
+  if (provision.status !== 'ok') {
+    return { ...base, status: 'provision-failed', provision }
+  }
+  const command = `set -e\ncd ${shellQuote(dir)}\n${plan.command}`
+  const result = await runGuest(ctx, command, { timeoutMs: options.timeoutMs ?? 30 * 60 * 1000, signal: options.signal })
+  if (result.status !== 'ok') {
+    return { ...base, status: 'build-failed', provision, stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode }
+  }
+
+  let artifact
+  if (plan.kind === 'rust') artifact = join(dir, plan.output)
+  else {
+    const packed = result.stdout?.match(/[^\s]+\.tgz/)?.[0]
+    artifact = packed !== undefined ? join(dir, packed.replace(/^\.\//, '')) : join(dir, 'package.tgz')
+  }
+  return {
+    ...base,
+    status: 'ok',
+    artifact,
+    provision,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    next: plan.kind === 'rust'
+      ? `compat_convert { spec: ${JSON.stringify(spec)}, workerPath: ${JSON.stringify(artifact)} }`
+      : `compat_convert { spec: ${JSON.stringify(artifact)} }`,
+  }
+}