dshm-compat 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.1.6
+
+- Native worker wrappers now bridge the DSHM host app-files prefix
+  `/data/storage/el2/base/haps/entry/files` to the guest's `/mnt/share` 9p
+  mount. `dsh-ops` passes the host `policy.workspaceRoot` as the worker's
+  `root`; the worker canonicalizes it before doing anything, so an unmapped
+  host path made every `ops_*` call fail with `NOT_FOUND` even when the guest
+  path existed. The wrapper creates the symlink only when the guest mount
+  exists and the host prefix is absent.
+- Offline regression suite: 30/30.
+
+## 0.1.5
+
+- Spawn rewriting now uses `['bash', file]` plus a staged shell wrapper instead
+  of `bash -c 'exec "$0" "$@"'`. `dshm-vm-bash` drops positional parameters for
+  `-c`, so the old form produced `Permission denied` and lost worker arguments.
+- `runGuestFile` and sidecars use the same non-`-c` path (`bash <wrapper> <args>`).
+- Release acquisition tries the package-version tag first, then the latest
+  release, falls back to the API asset endpoint, verifies `sha256` when
+  available, and returns attempts instead of a silent failure.
+- Source-only packages return `needs-build` with an external build contract;
+  when the same package has a published npm build, `convert` automatically
+  retries that build instead. Verified with `dsh-ops` 0.4.0 GitHub source:
+  it falls back to `dsh-ops@0.3.0` and produces a validated package.
+- Added `compat_build`: a source build planner for `Cargo.toml`/Node
+  `build`/`prepack` packages, plus an opt-in `backend:"guest"` attempt that
+  provisions Rust or Node in the Alpine guest and runs the build there. The
+  guest path depends on guest network/disk and is explicitly experimental.
+- Added `compat_uninstall` and `engines.dsh` normalization.
+- Offline regression suite: 30/30.
+
 ## 0.1.4
 
 - The generic S2 adapter now accepts **x86_64** workers: it bundles
@@ -16,7 +47,29 @@
 - Verified end-to-end: `compat_convert("https://github.com/T-Auto/dsh-ops")`
   with **no workerPath** acquires the upstream `linux-x64` release asset, wraps
   it in QEMU, patches the runtime/spawn/peer/os-cpu gates, and validates.
-- Offline regression suite: 27/27.
+- Spawn rewrite now uses `['bash', file]` and stages a shell wrapper around the
+  real worker instead of `bash -c 'exec "$0" "$@"'`. `dshm-vm-bash` drops
+  `$0`/`$@` for `-c` commands, which caused `Permission denied` and lost
+  arguments; the non-`-c` path preserves them.
+- Release selection first tries the tag matching the package version (`vX.Y.Z`),
+  then the latest release with assets; missing tags fall through instead of
+  returning an empty asset list.
+- Release download falls back from `browser_download_url` to the GitHub API
+  asset endpoint (`Accept: application/octet-stream`), records every attempt,
+  and verifies the asset `sha256` digest when GitHub provides one. Failures are
+  returned in `acquisition.attempts`, not swallowed.
+- The adapter also rewrites resolved-shell spawns (`[file, '-c', command]` and
+  `[file, scriptPath]`) to `['bash', '-c', command]` / `['bash', scriptPath]`,
+  so the shell component does not exec an ELF from the app sandbox.
+- `runGuestFile` now invokes `bash <script> <args>` instead of
+  `bash -c 'exec "$0" "$@"'`; sidecars stage a wrapper script so positional
+  arguments survive `dshm-vm-bash`.
+- Source packages with no built `main` and a `build`/`prepack` script return
+  `needs-build` with an external `npm ci && npm run build && npm pack` contract
+  instead of `recipe-mismatch`.
+- Added `compat_uninstall` for profile-local removal (node_modules + dependency
+  + bundle entry), and `engines.dsh` is stripped alongside `os`/`cpu`.
+- Offline regression suite: 28/28.
 
 ## 0.1.3
 

package/INSTALL.md

@@ -1,7 +1,7 @@
 # Installing dshm-compat
 
-The artifact is a normal DSH bundle package: `dshm-compat-0.1.4.tgz`.
-It is host-only, has no runtime dependencies, and adds ten agent tools.
+The artifact is a normal DSH bundle package: `dshm-compat-0.1.6.tgz`.
+It is host-only, has no runtime dependencies, and adds twelve agent tools.
 
 ## A. DSHM (the tablet)
 
@@ -15,7 +15,7 @@ input calls `pnpm view` before installing and fails with
 `Command failed with EACCES: pnpm view ... spawn pnpm EACCES`. Use one of these
 instead:
 
-- ask the DSHM Agent to run `pnpm add dshm-compat@0.1.4` in its bash tool (the
+- ask the DSHM Agent to run `pnpm add dshm-compat@0.1.6` in its bash tool (the
   bundled pnpm shim routes that command to the host install queue); or
 - install from a GitHub repository URL; or
 - after any working install, use the plugin's own `compat_install` tool for
@@ -28,7 +28,7 @@ not accept local paths, `file:` or `http://` specs.
 
 ### A2. HTTPS tarball
 
-Put `dshm-compat-0.1.4.tgz` on any HTTPS host (GitHub Release, Gitee Release,
+Put `dshm-compat-0.1.6.tgz` on any HTTPS host (GitHub Release, Gitee Release,
 object storage) and paste the `.tgz` URL into the same Add plugin input. DSHM's
 installer accepts tarball specs; if the current market UI refuses a plain URL,
 use A1.
@@ -38,7 +38,7 @@ use A1.
 If `hdc` is available and the app can read the path:
 
 ```sh
-hdc file send dshm-compat-0.1.4.tgz /data/storage/el2/base/haps/entry/files/dshm-compat-0.1.4.tgz
+hdc file send dshm-compat-0.1.6.tgz /data/storage/el2/base/haps/entry/files/dshm-compat-0.1.6.tgz
 ```
 
 Then enter the absolute path (or `file:/...`) in the Add plugin input. This
@@ -47,7 +47,7 @@ depends on the DSHM build's local-file support; A1 is safer.
 ## B. Desktop DSH (for testing only)
 
 ```powershell
-& 'D:\安装\dsh-desktop\resources\runtime\cli\bin\dsh.cmd' plugin --profile desktop add 'D:\dsh\dsh-26-09-30\dshm-compat\dshm-compat-0.1.4.tgz'
+& 'D:\安装\dsh-desktop\resources\runtime\cli\bin\dsh.cmd' plugin --profile desktop add 'D:\dsh\dsh-26-09-30\dshm-compat\dshm-compat-0.1.6.tgz'
 ```
 
 If the profile reports `ERR_PNPM_UNEXPECTED_VIRTUAL_STORE`, its `node_modules`

package/README.md

@@ -5,10 +5,11 @@ them through the least invasive strategy that can work.
 
 ## Current phase
 
-0.1.4 adds a generic S2 native adapter (including an x86_64 worker + bundled
-QEMU fallback and GitHub Release worker acquisition), `compat_doctor`,
-rollback-safe local installs, and codeload fallbacks for GitHub. Phase 1 ships
-the analyzer, the S0/S1 converter, the generic S2 engine, guest
+0.1.6 bridges the host app-files prefix to the guest `/mnt/share` mount for
+native worker roots, fixing `NOT_FOUND` from `ops_*`. 0.1.5 added non-`-c`
+spawn wrappers, release fallbacks, and `compat_uninstall`; 0.1.4 added the
+generic S2 adapter with x86_64 QEMU and GitHub Release acquisition. Phase 1
+ships the analyzer, the S0/S1 converter, the generic S2 engine, guest
 probing/provisioning, the DSHM install-queue transport, and a profile-local
 fallback for artifacts the host queue rejects:
 
@@ -25,8 +26,10 @@ fallback for artifacts the host queue rejects:
   `workerPath`, the package's `runtime/linux-*`, or the GitHub Release assets
   (linux-arm64 first, then linux-x64). An x86_64 worker is executed through the
   bundled `qemu-x86_64` and glibc rootfs, so no AArch64 rebuild is required.
-  Only when none of these exist does it return `needs-native-build` with the
-  cross-build command. Package names are not special-cased.
+  A source-only checkout is retried against the package's published npm build
+  (with a `fallback` field in the result); only when neither a worker nor a
+  published build exists does it return `needs-build`/`needs-native-build` with
+  the external build command. Package names are not special-cased.
 - `compat_guest_probe` reports the Alpine guest kernel/packages/tools.
 - `compat_guest_provision` installs a reviewed allowlist of Alpine packages in
   the guest (`confirm:true` required).
@@ -39,13 +42,19 @@ fallback for artifacts the host queue rejects:
   `.tgz` paths (and `file:`/`link:`) are unpacked directly into the owning DSH
   profile and its bundle list, then need a DSHM restart; this is required
   because the DSHM host queue rejects local specs.
+- `compat_build` plans a source build (PC/CI commands) or, with
+  `backend:"guest"` and `confirm:true`, provisions Node/Rust in the Alpine
+  guest and attempts the build there. The guest path is experimental and
+  depends on guest network/disk.
+- `compat_uninstall` removes a profile-local package, its dependency entry, and
+  its bundle entry; it also needs a restart.
 - `compat_convert` with `install:true` uses the same local fallback for its
   converted tarball.
 
-The converter deliberately stops at the manifest/repack/vendor boundary:
-source transpilation and native builds are later phases. A report saying
-`S2`/`S3`/`S4` is returned as-is rather than being reported as a successful
-conversion.
+The converter stops at the manifest/repack/vendor boundary for S0/S1. S2 also
+returns `needs-build` for a source-only package or `needs-native-build` when no
+Linux worker can be obtained. It does not silently claim that an unsupported
+native build succeeded.
 
 See [architecture](docs/ARCHITECTURE.md) and [conversion recipes](docs/RECIPES.md).
 

package/docs/ARCHITECTURE.md

@@ -61,6 +61,8 @@ spec ──► resolve (npm / GitHub / local .tgz)
 | `lib/guest.js` | read-only Alpine guest probe through `subprocess` |
 | `lib/install.js` | DSHM install-queue producer with polling and cancellation |
 | `lib/local-install.js` | profile-local tarball install with staging, backup, and rollback |
+| `lib/uninstall.js` | profile-local removal of files, dependency, and bundle entry |
+| `lib/source-build.js` | source-build planner and experimental guest build |
 | `lib/sidecar.js` | generic guest worker staging and JSON-stdio calls |
 | `lib/doctor.js` | one-shot DSHM/core/profile/queue/guest diagnosis |
 | `lib/state.js` | bounded report/install index and atomic writes |
@@ -79,6 +81,8 @@ spec ──► resolve (npm / GitHub / local .tgz)
 | `compat_sidecar` | stages/lists/probes/calls a JSON-stdio native worker in the guest |
 | `compat_doctor` | read-only DSHM/core/profile/queue/guest diagnosis |
 | `compat_install` | writes one install-queue request; runs third-party code |
+| `compat_build` | plans a source build, or provisions a guest toolchain and runs it with confirm:true |
+| `compat_uninstall` | removes a profile-local package, dependency, and bundle entry |
 | `compat_status` | read-only |
 
 ## Phase status

package/docs/RECIPES.md

@@ -24,14 +24,36 @@ For each match it:
   resolves to that target in both `resolveWorker` and `tryResolveWorker`;
 - replaces `${platform}-${arch}` **inside template literals** with
   `${resolveTarget(platform, arch)}`;
-- wraps every standard spawn call in
-  `['bash', '-c', 'exec "$0" "$@"', file]`, which `dshm-vm-bash` routes to the
-  Alpine guest;
-- removes `os`/`cpu`, drops win32/darwin optional payloads, and relaxes
-  `@deepseek-ai/dsh` to `workspace:*`;
+- rewrites every standard spawn call to `['bash', file]` and stages a shell
+  wrapper at `file` that `exec`s the real worker with `"$@"`. The
+  non-`-c` path is required because `dshm-vm-bash` drops positional parameters
+  for `bash -c`; the wrapper preserves the worker's argv;
+- removes `os`/`cpu`/`engines.dsh`, drops win32/darwin optional payloads, and
+  relaxes `@deepseek-ai/dsh` to `workspace:*`;
 - adds `openharmony`/target/arch to `dsh-plugin.json` component targets;
-- stages the worker at `runtime/<target>/<worker>` with a matching
-  `provenance.json` (`version`, `target`, `executable`, `sha256`).
+- stages the wrapper at `runtime/<target>/<worker>` and the real binary at
+  `<worker>-bin` (AArch64) or `<worker>-x64` (x86_64), with a matching
+  `provenance.json` (`version`, `target`, `executable`, `sha256`). The wrapper
+  also links the host app-files prefix
+  `/data/storage/el2/base/haps/entry/files` to the guest `/mnt/share` mount, so
+  a worker that canonicalizes the host `policy.workspaceRoot` sees a real path.
+
+A source package whose `main` is absent but which has a `build`/`prepack` script
+returns `needs-build` with `npm ci && npm run build && npm pack`; the produced
+tarball is then passed back to `compat_convert`. Before returning that, the
+converter retries the package's latest published npm build and records a
+`fallback` field when it succeeds. This keeps a source checkout from being
+misreported as a broken recipe while still preferring a runnable published build.
+
+### Guest source build
+
+`compat_build { spec, backend: "plan" }` returns the exact PC/CI commands. With
+`backend: "guest"` and `confirm: true`, the plugin provisions Node or Rust in
+the Alpine guest and runs the detected command (`cargo build --release`, or
+`npm ci && npm run build && npm pack`). This is experimental: it needs guest
+network, enough guest disk for the toolchain, and a guest-visible source
+directory. A failure returns the exact `apk`/build stderr; fall back to an
+external build and pass the produced artifact to `compat_convert`.
 
 An x86_64 worker is staged as a shell wrapper plus `qemu-x86_64`, a minimal
 x86_64 glibc rootfs, and the original `<worker>-x64`; the wrapper runs QEMU in

package/index.js

@@ -14,8 +14,10 @@ import { runDoctor } from './lib/doctor.js'
 import { probeGuest, provisionGuest } from './lib/guest.js'
 import { enqueueInstall } from './lib/install.js'
 import { installLocalTarball, isLocalSpec } from './lib/local-install.js'
+import { uninstallLocalPackage } from './lib/uninstall.js'
 import { buildPlan } from './lib/plan.js'
 import { callSidecar, listSidecars, probeSidecar, stageSidecar } from './lib/sidecar.js'
+import { buildSource } from './lib/source-build.js'
 import { recordInstall, recordReport, status } from './lib/state.js'
 
 export const name = 'dshm-compat'
@@ -277,6 +279,62 @@ export function apply(ctx) {
     },
   ), 'compat_sidecar')
 
+  register(definition(
+    'compat_build',
+    'Plan or attempt a source build. backend:"plan" returns the exact PC/CI commands; backend:"guest" provisions Node/Rust in the Alpine guest and tries the build there (slow, needs guest network/disk; requires confirm:true). Returns the artifact path on success.',
+    {
+      type: 'object',
+      properties: {
+        spec: { type: 'string', description: 'Source package: npm name, GitHub URL, or local .tgz.' },
+        backend: { type: 'string', enum: ['plan', 'guest'], description: 'plan (default) or guest.' },
+        timeoutMs: { type: 'integer', description: 'Guest build timeout. Default 30 minutes.' },
+        confirm: { type: 'boolean', description: 'Required for backend:"guest". Confirms provisioning a toolchain and running build scripts in the guest.' },
+      },
+      required: ['spec'],
+      additionalProperties: false,
+    },
+    async (args, exec) => {
+      try {
+        if (args?.backend === 'guest' && args.confirm !== true) {
+          return { status: 'confirmation-required', message: 'Re-run with confirm:true to provision a toolchain and run source build scripts in the guest.' }
+        }
+        return await buildSource(ctx, args.spec, {
+          backend: args.backend === 'guest' ? 'guest' : 'plan',
+          timeoutMs: args.timeoutMs,
+          signal: exec?.signal,
+        })
+      } catch (error) {
+        return errorResult(error)
+      }
+    },
+  ), 'compat_build')
+
+  register(definition(
+    'compat_uninstall',
+    'Remove a profile-local plugin: delete profiles/<profile>/node_modules/<name>, remove its dependency entry, and remove it from dsh.profile.bundles. Requires confirm:true and a DSHM restart.',
+    {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Installed package name, e.g. @scope/plugin.' },
+        profileDir: { type: 'string', description: 'Absolute DSHM profile directory. Omit to infer it.' },
+        confirm: { type: 'boolean', description: 'Must be true. Confirms removing the package from the profile.' },
+      },
+      required: ['name', 'confirm'],
+      additionalProperties: false,
+    },
+    async args => {
+      if (args?.confirm !== true) {
+        return { status: 'confirmation-required', message: 'Re-run with confirm:true to remove the package from the profile.' }
+      }
+      try {
+        const result = uninstallLocalPackage(args.name, { profileDir: args.profileDir })
+        return result.ok ? { status: 'ok', ...result } : { status: 'error', ...result }
+      } catch (error) {
+        return errorResult(error)
+      }
+    },
+  ), 'compat_uninstall')
+
   register(definition(
     'compat_install',
     'Install an already-built plugin artifact. Local .tgz paths (or file:/link: paths) are unpacked into the owning DSH profile and its bundle list, because DSHM\'s host queue rejects local specs; npm names and GitHub repositories still go through the host install queue. '

package/lib/analyze.js

@@ -329,6 +329,9 @@ export async function analyze(spec, options = {}) {
       description: pkg.description,
       type: pkg.type,
       main: pkg.main,
+      repository: pkg.repository,
+      homepage: pkg.homepage,
+      bugs: pkg.bugs,
       os: pkg.os,
       cpu: pkg.cpu,
       scripts,

package/lib/convert.js

@@ -41,21 +41,69 @@ function safeName(name) {
   return String(name).replace(/^@/, '').replace(/[\\/]/g, '-').replace(/[^A-Za-z0-9._-]/g, '_')
 }
 
+/**
+ * A GitHub source checkout may have no built `main`. Prefer the package's
+ * published npm build instead of stopping at needs-build; this is generic and
+ * keeps the source version only when the registry has nothing newer/built.
+ *
+ * @param {any} report
+ * @param {any} options
+ */
+async function registryFallback(report, options) {
+  const name = report.package?.name
+  if (typeof name !== 'string' || name === '' || options.registryFallback === true) return undefined
+  let resolved
+  try {
+    resolved = await resolveSpec(`${name}@latest`, { registry: options.registry, signal: options.signal })
+  } catch {
+    return undefined
+  }
+  const version = typeof resolved.version === 'string' ? resolved.version : undefined
+  if (version === undefined || version === report.package.version) return undefined
+  let fallbackReport
+  try {
+    fallbackReport = await analyze(`${name}@latest`, { textScan: false, signal: options.signal, registry: options.registry })
+  } catch {
+    return undefined
+  }
+  if (fallbackReport.strategy !== 'S2') return undefined
+  const { convertS2Native } = await import('./s2-native.js')
+  const converted = await convertS2Native(`${name}@latest`, {
+    report: fallbackReport,
+    workerPath: options.workerPath,
+    workerBinary: options.workerBinary,
+    workerName: options.workerName,
+    signal: options.signal,
+    registryFallback: true,
+  })
+  if (converted.status !== 'ok') return undefined
+  return {
+    ...converted,
+    fallback: { from: report.spec, to: `${name}@${version}`, version },
+    changed: [...(converted.changed ?? []), `replaced source checkout with published ${name}@${version}`],
+  }
+}
+
 /**
  * @param {string} spec
- * @param {{ report?: any, registry?: string, signal?: AbortSignal, maxBytes?: number }} [options]
+ * @param {{ report?: any, registry?: string, signal?: AbortSignal, maxBytes?: number, workerPath?: string, workerBinary?: Buffer, workerName?: string, registryFallback?: boolean }} [options]
  */
 export async function convert(spec, options = {}) {
   const report = options.report ?? await analyze(spec, { textScan: false, signal: options.signal, registry: options.registry })
   if (report.strategy === 'S2') {
     const { convertS2Native } = await import('./s2-native.js')
-    return await convertS2Native(spec, {
+    const result = await convertS2Native(spec, {
       report,
       workerPath: options.workerPath,
       workerBinary: options.workerBinary,
       workerName: options.workerName,
       signal: options.signal,
     })
+    if (result.status === 'needs-build' && result.sourcePackage === true) {
+      const fallback = await registryFallback(report, options)
+      if (fallback !== undefined) return fallback
+    }
+    return result
   }
   if (report.strategy !== 'S0' && report.strategy !== 'S1') {
     return {
@@ -97,6 +145,11 @@ export async function convert(spec, options = {}) {
 
   if (pkg.os !== undefined) { delete pkg.os; changed.push('removed package.json os gate') }
   if (pkg.cpu !== undefined) { delete pkg.cpu; changed.push('removed package.json cpu gate') }
+  if (pkg.engines !== null && typeof pkg.engines === 'object' && !Array.isArray(pkg.engines) && pkg.engines.dsh !== undefined) {
+    delete pkg.engines.dsh
+    if (Object.keys(pkg.engines).length === 0) delete pkg.engines
+    changed.push('removed engines.dsh gate')
+  }
   if (pkg.scripts !== null && typeof pkg.scripts === 'object' && !Array.isArray(pkg.scripts)) {
     for (const name of ['preinstall', 'install', 'postinstall', 'prepare']) {
       if (typeof pkg.scripts[name] === 'string') { delete pkg.scripts[name]; changed.push(`removed scripts.${name}`) }

package/lib/guest.js

@@ -30,6 +30,8 @@ export const PROVISION_PACKAGES = Object.freeze([
   'python3',
   'build-base',
   'linux-headers',
+  'rust',
+  'cargo',
   'git',
   'ffmpeg',
 ])
@@ -113,7 +115,7 @@ export async function runGuestFile(ctx, file, args = [], input = '', options = {
   if (options.signal) signals.push(options.signal)
   try {
     const handle = subprocess.spawn({
-      argv: ['bash', '-c', 'exec "$0" "$@"', file, ...args.map(String)],
+      argv: ['bash', file, ...args.map(String)],
       cwd: options.cwd ?? '/',
       stdio: {
         ...(input !== '' ? { stdin: { data: input } } : {}),

package/lib/release.js

@@ -8,6 +8,7 @@
  *
  * @module dshm-compat/release
  */
+import { createHash } from 'node:crypto'
 import { basename } from 'node:path'
 import { elfArch } from './elf.js'
 import { downloadBuffer } from './fetch.js'
@@ -23,8 +24,12 @@ export function githubRepo(report) {
     if (owner && repo) return { owner, repo }
   }
   const repository = report?.package?.repository
-  const url = typeof repository === 'string' ? repository : repository?.url
-  if (typeof url === 'string') {
+  const candidates = [
+    typeof repository === 'string' ? repository : repository?.url,
+    typeof report?.package?.homepage === 'string' ? report.package.homepage : undefined,
+    typeof report?.package?.bugs === 'string' ? report.package.bugs : report?.package?.bugs?.url,
+  ].filter(value => typeof value === 'string')
+  for (const url of candidates) {
     const match = url.match(/github\.com[/:]([^/]+)\/([^/#?]+)/i)
     if (match) return { owner: match[1], repo: match[2].replace(/\.git$/i, '') }
   }
@@ -48,11 +53,19 @@ async function fetchJson(url, signal) {
   return await response.json()
 }
 
-/** @param {string} owner @param {string} repo @param {AbortSignal} [signal] */
-async function releaseAssets(owner, repo, signal) {
+/** @param {string} owner @param {string} repo @param {string|undefined} version @param {AbortSignal} [signal] */
+async function releaseAssets(owner, repo, version, signal) {
+  if (typeof version === 'string' && version !== '') {
+    for (const tag of [`v${version}`, version]) {
+      try {
+        const tagged = await fetchJson(`${API}/repos/${owner}/${repo}/releases/tags/${encodeURIComponent(tag)}`, signal)
+        if (Array.isArray(tagged?.assets) && tagged.assets.length > 0) return tagged.assets
+      } catch { /* try the next tag, then the latest release */ }
+    }
+  }
   try {
     const latest = await fetchJson(`${API}/repos/${owner}/${repo}/releases/latest`, signal)
-    if (Array.isArray(latest?.assets)) return latest.assets
+    if (Array.isArray(latest?.assets) && latest.assets.length > 0) 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[]} */
@@ -85,34 +98,88 @@ function archiveEntries(archive, name) {
 /**
  * @param {any} report
  * @param {{ signal?: AbortSignal }} [options]
- * @returns {Promise<{ buffer: Buffer, name: string, arch: 'arm64'|'x64', asset: string } | undefined>}
+ * @returns {Promise<
+ *   | { ok: true, buffer: Buffer, name: string, arch: 'arm64'|'x64', asset: string, sha256: string, attempts: any[] }
+ *   | { ok: false, reason: string, attempts: any[] }
+ * >}
  */
 export async function findReleaseWorker(report, options = {}) {
+  const attempts = []
   const repo = githubRepo(report)
-  if (repo === undefined) return undefined
+  if (repo === undefined) return { ok: false, reason: 'no GitHub repository in the package metadata', attempts }
+
   let assets
-  try { assets = await releaseAssets(repo.owner, repo.repo, options.signal) } catch { return undefined }
+  try {
+    assets = await releaseAssets(repo.owner, repo.repo, report?.package?.version ?? report?.resolved?.version, options.signal)
+  } catch (error) {
+    return { ok: false, reason: `GitHub release lookup failed: ${String(error?.message ?? error)}`, attempts }
+  }
   const ranked = assets
     .map(asset => ({ asset, rank: assetRank(asset) }))
     .filter(item => item.rank !== undefined)
     .sort((a, b) => a.rank - b.rank)
+  if (ranked.length === 0) return { ok: false, reason: 'no Linux worker asset in the latest releases', attempts }
+
   for (const { asset } of ranked) {
-    if (typeof asset.browser_download_url !== 'string' || Number(asset.size ?? 0) > 64 * 1024 * 1024) continue
+    if (Number(asset.size ?? 0) > 64 * 1024 * 1024) {
+      attempts.push({ asset: asset.name, stage: 'size', error: `asset is larger than 64 MiB` })
+      continue
+    }
+    const urls = [asset.browser_download_url]
+    if (asset.id !== undefined) urls.push(`${API}/repos/${repo.owner}/${repo.repo}/releases/assets/${asset.id}`)
     let archive
-    try { archive = await downloadBuffer(asset.browser_download_url, { maxBytes: 64 * 1024 * 1024, signal: options.signal }) } catch { continue }
+    let downloadedUrl
+    for (const url of urls) {
+      if (typeof url !== 'string') continue
+      try {
+        archive = await downloadBuffer(url, {
+          maxBytes: 64 * 1024 * 1024,
+          signal: options.signal,
+          headers: url.includes('/releases/assets/') ? { accept: 'application/octet-stream' } : {},
+        })
+        downloadedUrl = url
+        attempts.push({ asset: asset.name, url, stage: 'download', ok: true })
+        break
+      } catch (error) {
+        attempts.push({ asset: asset.name, url, stage: 'download', error: String(error?.message ?? error) })
+      }
+    }
+    if (archive === undefined || downloadedUrl === undefined) continue
+
+    const digestMatch = typeof asset.digest === 'string' ? asset.digest.match(/^sha256:([a-f0-9]{64})$/i) : null
+    if (digestMatch !== null) {
+      const actual = createHash('sha256').update(archive).digest('hex')
+      if (actual !== digestMatch[1].toLowerCase()) {
+        attempts.push({ asset: asset.name, stage: 'sha256', error: `expected ${digestMatch[1]}, got ${actual}` })
+        continue
+      }
+    }
+
     let entries
-    try { entries = archiveEntries(archive, asset.name) } catch { continue }
+    try {
+      entries = archiveEntries(archive, asset.name)
+    } catch (error) {
+      attempts.push({ asset: asset.name, stage: 'extract', error: String(error?.message ?? error) })
+      continue
+    }
     const candidates = entries
       .filter(entry => elfArch(entry.data) !== undefined)
       .sort((a, b) => b.data.length - a.data.length)
-    if (candidates.length === 0) continue
+    if (candidates.length === 0) {
+      attempts.push({ asset: asset.name, stage: 'worker', error: 'archive contains no AArch64/x86_64 ELF' })
+      continue
+    }
     const worker = candidates[0]
+    attempts.push({ asset: asset.name, url: downloadedUrl, stage: 'worker', ok: true })
     return {
+      ok: true,
       buffer: worker.data,
       name: basename(worker.path),
       arch: elfArch(worker.data),
       asset: asset.name,
+      sha256: createHash('sha256').update(worker.data).digest('hex'),
+      attempts,
     }
   }
-  return undefined
+  return { ok: false, reason: 'no usable Linux worker asset could be downloaded', attempts }
 }

package/lib/s2-native.js

@@ -57,6 +57,27 @@ export async function convertS2Native(spec, options = {}) {
   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') {
@@ -78,12 +99,13 @@ export async function convertS2Native(spec, options = {}) {
     }
   }
   let acquiredAsset
+  let acquisition
   if (workerBinary === undefined) {
-    const releaseWorker = await findReleaseWorker(report, { signal: options.signal })
-    if (releaseWorker !== undefined) {
-      workerBinary = releaseWorker.buffer
-      workerName = releaseWorker.name
-      acquiredAsset = releaseWorker.asset
+    acquisition = await findReleaseWorker(report, { signal: options.signal })
+    if (acquisition.ok === true) {
+      workerBinary = acquisition.buffer
+      workerName = acquisition.name
+      acquiredAsset = acquisition.asset
     }
   }
   if (workerBinary === undefined) {
@@ -96,6 +118,7 @@ export async function convertS2Native(spec, options = {}) {
         '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)
@@ -109,6 +132,26 @@ export async function convertS2Native(spec, options = {}) {
     && 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')
@@ -131,8 +174,10 @@ export async function convertS2Native(spec, options = {}) {
     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]")
+      .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) {
@@ -144,6 +189,10 @@ export async function convertS2Native(spec, options = {}) {
   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.
@@ -178,27 +227,47 @@ export async function convertS2Native(spec, options = {}) {
   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([
+  let stagedWorker
+  let workerSource
+  try {
+    const hostFilesLink = [
+      '# DSHM host app-files prefix -> guest 9p mount',
+      'if [ -d /mnt/share ] && [ ! -e /data/storage/el2/base/haps/entry/files ] && [ ! -L /data/storage/el2/base/haps/entry/files ]; then',
+      '  mkdir -p /data/storage/el2/base/haps/entry 2>/dev/null || true',
+      '  ln -s /mnt/share /data/storage/el2/base/haps/entry/files 2>/dev/null || true',
+      'fi',
+    ]
+    if (workerArch === 'x64') {
+      const realName = `${workerName}-x64`
+      stagedWorker = Buffer.from([
         '#!/bin/sh',
         'set -e',
+        ...hostFilesLink,
         'DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)',
-        `exec "$DIR/qemu-x86_64" -L "$DIR/rootfs" "$DIR/${workerName}-x64" "$@"`,
+        `exec "$DIR/qemu-x86_64" -L "$DIR/rootfs" "$DIR/${realName}" "$@"`,
         '',
       ].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}/${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 })
-    } catch (error) {
-      return { status: 'invalid-output', error: `cannot stage the bundled qemu runtime: ${String(error?.message ?? error)}` }
+    } else {
+      const realName = `${workerName}-bin`
+      stagedWorker = Buffer.from([
+        '#!/bin/sh',
+        'set -e',
+        ...hostFilesLink,
+        '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 = {
@@ -212,14 +281,16 @@ export async function convertS2Native(spec, options = {}) {
   /** @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`,
+    `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 ${workerPath}`,
+      : `staged ${workerName} as a shell wrapper over ${workerName}-bin`,
+    'mapped /data/storage/el2/base/haps/entry/files to the guest /mnt/share mount',
   ]
 
   const output = files.filter(file => file.path !== workerPath).map(file => {
@@ -249,6 +320,7 @@ export async function convertS2Native(spec, options = {}) {
     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

@@ -98,10 +98,19 @@ export function stageSidecar(tarball, workerPath, options = {}) {
     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,
@@ -133,7 +142,8 @@ export async function callSidecar(ctx, id, input, options = {}) {
   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 ?? {}), {
+  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,
   })
@@ -159,7 +169,8 @@ export async function probeSidecar(ctx, id, options = {}) {
   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'], '', {
+  const file = typeof meta.script === 'string' ? meta.script : meta.worker
+  const result = await runGuestFile(ctx, file, ['--version'], '', {
     timeoutMs: options.timeoutMs ?? 30000,
     signal: options.signal,
   })

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)} }`,
+  }
+}

package/lib/uninstall.js

@@ -0,0 +1,94 @@
+/**
+ * Profile-local uninstall.
+ *
+ * Removes a package from the owning profile: its `node_modules` directory, the
+ * `dependencies` entry, and the `dsh.profile.bundles` entry. The profile
+ * manifest is only changed after the files are moved aside, so a failed delete
+ * can be rolled back.
+ *
+ * @module dshm-compat/uninstall
+ */
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveProfileDir } from './local-install.js'
+
+/** @param {unknown} value */
+function record(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined
+}
+
+/** @param {string} file */
+function readJson(file) {
+  try { return JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, '')) } catch { return undefined }
+}
+
+/** @param {string} file @param {unknown} value */
+function writeJsonAtomic(file, value) {
+  const temporary = `${file}.tmp-${process.pid}-${Date.now()}`
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
+  renameSync(temporary, file)
+}
+
+/**
+ * @param {string} name
+ * @param {{ profileDir?: string, env?: NodeJS.ProcessEnv }} [options]
+ */
+export function uninstallLocalPackage(name, options = {}) {
+  const env = options.env ?? process.env
+  if (typeof name !== 'string' || !/^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/i.test(name)) {
+    return { ok: false, error: `invalid package name: ${String(name)}` }
+  }
+  const profileDir = typeof options.profileDir === 'string' && options.profileDir !== ''
+    ? options.profileDir
+    : resolveProfileDir(env)
+  if (profileDir === undefined) return { ok: false, error: 'cannot locate the DSH profile; pass profileDir explicitly' }
+  const manifestPath = join(profileDir, 'package.json')
+  const manifest = record(readJson(manifestPath))
+  if (manifest === undefined) return { ok: false, error: `profile manifest is not an object: ${manifestPath}` }
+
+  const destination = join(profileDir, 'node_modules', ...name.split('/'))
+  const dependencies = record(manifest.dependencies) ?? {}
+  const hadDependency = Object.prototype.hasOwnProperty.call(dependencies, name)
+  const dsh = record(manifest.dsh) ?? {}
+  const profile = record(dsh.profile) ?? {}
+  const bundles = Array.isArray(profile.bundles) ? profile.bundles.filter(item => typeof item === 'string') : []
+  const hadBundle = bundles.includes(name)
+  if (!hadDependency && !hadBundle && !existsSync(destination)) {
+    return { ok: true, name, removed: false, profileDir, restartRequired: false, message: 'not installed in this profile' }
+  }
+
+  const backup = `${destination}.uninstall-${process.pid}-${Date.now()}`
+  const originalManifest = JSON.parse(JSON.stringify(manifest))
+  let moved = false
+  try {
+    if (existsSync(destination)) {
+      renameSync(destination, backup)
+      moved = true
+    }
+    delete dependencies[name]
+    manifest.dependencies = dependencies
+    profile.bundles = bundles.filter(item => item !== name)
+    dsh.profile = profile
+    manifest.dsh = dsh
+    writeJsonAtomic(manifestPath, manifest)
+    if (moved) {
+      try { rmSync(backup, { recursive: true, force: true }) } catch { /* keep the backup if it is locked */ }
+    }
+    return {
+      ok: true,
+      name,
+      removed: true,
+      profileDir,
+      destination,
+      removedDependency: hadDependency,
+      removedBundle: hadBundle,
+      restartRequired: true,
+    }
+  } catch (error) {
+    try { writeJsonAtomic(manifestPath, originalManifest) } catch { /* best effort */ }
+    if (moved && existsSync(backup)) {
+      try { renameSync(backup, destination) } catch { /* best effort */ }
+    }
+    return { ok: false, error: `uninstall failed: ${String(error?.message ?? error)}` }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dshm-compat",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Analyze and convert DSH plugins that cannot be installed or run on HarmonyOS DSHM.",
   "type": "module",
   "main": "index.js",