dshm-compat 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.1.2
+
+- Added `compat_doctor`: one read-only diagnosis of DSHM mode, core version,
+  owning profile/bundle registration, install queue, state, and the Alpine
+  guest (bash/apk/node).
+- Local installs now stage into a sibling directory, move the old install to a
+  backup, and restore it if writing the new tree or the profile manifest fails.
+- GitHub specs now carry codeload fallbacks (`HEAD`, `refs/heads/main`,
+  `refs/heads/master`) when the API tarball endpoint fails or is rate-limited.
+- Offline regression suite: 23/23.
+
+## 0.1.1
+
+- Tool results are now lossless JSON: `undefined`-valued fields are stripped at
+  the tool boundary. This fixes `compat_analyze` / `compat_plan` / `compat_scan`
+  failing with `value is not lossless JSON` on DSHM.
+- Local tarball installation: `compat_install` (and `compat_convert` with
+  `install:true`) unpacks a `.tgz` into the owning DSH profile's `node_modules`,
+  records the dependency, and appends the bundle. This works around DSHM's host
+  installer rejecting local paths, `file:` and `http://` specs. A restart is
+  required, and the result says `restartRequired: true`.
+- Local install preserves the tarball's file modes (needed for native worker
+  binaries such as `dsh-ops-worker`).
+- Docs updated with the DSHM `pnpm view` limitation and the local install path.
+
+## 0.1.0
+
+- Initial analyzer, S0/S1 converter, dependency preflight/vendoring, guest
+  probe/provision, install queue, and dsh-ops 0.3.x recipe.

package/INSTALL.md

@@ -1,23 +1,34 @@
 # Installing dshm-compat
 
-The artifact is a normal DSH bundle package: `dshm-compat-0.1.0.tgz`.
+The artifact is a normal DSH bundle package: `dshm-compat-0.1.2.tgz`.
 It is host-only, has no runtime dependencies, and adds eight agent tools.
 
 ## A. DSHM (the tablet)
 
-### A1. npm or GitHub (recommended)
+### A1. npm or GitHub
 
 Publish the package to npm (remove `"private": true` from `package.json`
-first), or push this directory to a GitHub repository, then in DSHM:
+first), or push this directory to a GitHub repository.
 
-1. Open **Settings → Plugins → Add plugin**.
-2. Enter `dshm-compat` (npm) or the GitHub repository URL.
-3. Install, enable the bundle, and restart DSHM if the app asks for it.
-4. Confirm the plugin card shows **DSHM Plugin Compatibility**.
+On DSHM builds without a shell, the official **Settings → Plugins → Add plugin**
+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.2` 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
+  npm/GitHub specs.
+
+The plugin's local converted tarballs are installed by `compat_install` itself:
+it unpacks them into `profiles/<profile>/node_modules/<name>`, records the
+dependency and bundle, and asks for a DSHM restart. The host install queue does
+not accept local paths, `file:` or `http://` specs.
 
 ### A2. HTTPS tarball
 
-Put `dshm-compat-0.1.0.tgz` on any HTTPS host (GitHub Release, Gitee Release,
+Put `dshm-compat-0.1.2.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.
@@ -27,7 +38,7 @@ use A1.
 If `hdc` is available and the app can read the path:
 
 ```sh
-hdc file send dshm-compat-0.1.0.tgz /data/storage/el2/base/haps/entry/files/dshm-compat-0.1.0.tgz
+hdc file send dshm-compat-0.1.2.tgz /data/storage/el2/base/haps/entry/files/dshm-compat-0.1.2.tgz
 ```
 
 Then enter the absolute path (or `file:/...`) in the Add plugin input. This
@@ -36,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.0.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.2.tgz'
 ```
 
 If the profile reports `ERR_PNPM_UNEXPECTED_VIRTUAL_STORE`, its `node_modules`

package/README.md

@@ -5,8 +5,10 @@ them through the least invasive strategy that can work.
 
 ## Current phase
 
-Phase 1 ships the analyzer, the S0/S1 converter, the dsh-ops recipe, guest
-probing/provisioning, and the DSHM install-queue transport:
+0.1.2 adds `compat_doctor`, rollback-safe local installs, and codeload
+fallbacks for GitHub. Phase 1 ships the analyzer, the S0/S1 converter, the
+dsh-ops recipe, guest probing/provisioning, the DSHM install-queue transport,
+and a profile-local fallback for artifacts the host queue rejects:
 
 - `compat_analyze` downloads an npm/GitHub/local package and classifies it.
 - `compat_plan` returns the concrete conversion plan without changing anything.
@@ -22,8 +24,14 @@ probing/provisioning, and the DSHM install-queue transport:
 - `compat_guest_provision` installs a reviewed allowlist of Alpine packages in
   the guest (`confirm:true` required).
 - `compat_status` lists stored reports and install attempts.
-- `compat_install` submits an already-built tarball to the host install queue
-  (`confirm:true` required).
+- `compat_doctor` checks DSHM mode, core, profile/bundle, queue, state, and the
+  guest in one read-only call.
+- `compat_install` installs an npm/GitHub spec through the host queue. Local
+  `.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_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

package/docs/ARCHITECTURE.md

@@ -57,6 +57,8 @@ spec ──► resolve (npm / GitHub / local .tgz)
 | `lib/plan.js` | user-visible conversion plan for every strategy |
 | `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/doctor.js` | one-shot DSHM/core/profile/queue/guest diagnosis |
 | `lib/state.js` | bounded report/install index and atomic writes |
 | `lib/pack.js` | dependency-free ustar/gzip writer |
 
@@ -70,6 +72,7 @@ spec ──► resolve (npm / GitHub / local .tgz)
 | `compat_convert` | writes a converted tarball; optionally submits it to the install queue |
 | `compat_guest_probe` | read-only guest command |
 | `compat_guest_provision` | installs allowlisted Alpine packages 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_status` | read-only |
 

package/index.js

@@ -10,8 +10,10 @@
 import { analyze } from './lib/analyze.js'
 import { scan } from './lib/batch.js'
 import { convert } from './lib/convert.js'
+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 { buildPlan } from './lib/plan.js'
 import { recordInstall, recordReport, status } from './lib/state.js'
 
@@ -47,7 +49,13 @@ function definition(name, description, parameters, execute) {
     description: description + RESULT_NOTE,
     parameters,
     output: { schema: OUTPUT, render: renderJson },
-    execute,
+    // DSH validates tool results as lossless JSON; undefined-valued fields are
+    // rejected. Strip them once at the boundary so every tool is safe.
+    execute: async (args, exec) => {
+      const value = await execute(args, exec)
+      if (value === undefined) return null
+      try { return JSON.parse(JSON.stringify(value)) } catch (error) { return errorResult(error) }
+    },
   }
 }
 
@@ -145,6 +153,7 @@ export function apply(ctx) {
         confirm: { type: 'boolean', description: 'Required when install is true. Confirms that installing the converted package runs third-party code.' },
         vendor: { type: 'boolean', description: 'Vendor missing pure-JS runtime dependencies into the tarball. Default true.' },
         workerPath: { type: 'string', description: 'Absolute path to a prebuilt AArch64 Linux worker for recipes that need one (currently dsh-ops). Omit to receive the build command instead.' },
+        allowLocal: { type: 'boolean', description: 'When install is true, unpack the converted tarball into the profile instead of the host queue. Default true; set false to force the queue.' },
       },
       required: ['spec'],
       additionalProperties: false,
@@ -160,7 +169,10 @@ export function apply(ctx) {
         if (args.confirm !== true) {
           return { ...result, install: { status: 'confirmation-required', message: 'Re-run with install:true and confirm:true to submit the tarball.' } }
         }
-        const installed = await enqueueInstall(`file:${result.tarball}`, { profileDir: args.profileDir, signal: exec?.signal })
+        const local = args.allowLocal === false ? undefined : installLocalTarball(result.tarball, { profileDir: args.profileDir })
+        const installed = local === undefined
+          ? await enqueueInstall(`file:${result.tarball}`, { profileDir: args.profileDir, signal: exec?.signal })
+          : { status: local.ok ? 'ok' : 'error', ...local }
         recordInstall({ spec: args.spec, tarball: result.tarball, at: new Date().toISOString(), ...installed })
         return { ...result, install: installed }
       } catch (error) {
@@ -178,6 +190,15 @@ export function apply(ctx) {
     },
   ), 'compat_status')
 
+  register(definition(
+    'compat_doctor',
+    'One-shot diagnosis of the DSHM environment: whether this is DSHM, the core version, the owning profile and bundle registration, the install queue, stored state, and the Alpine guest (bash/apk/node). Read-only.',
+    { type: 'object', properties: {}, additionalProperties: false },
+    async (_args, exec) => {
+      try { return { status: 'ok', ...(await runDoctor(ctx, process.env)) } } catch (error) { return errorResult(error) }
+    },
+  ), 'compat_doctor')
+
   register(definition(
     'compat_guest_probe',
     'Probe the DSHM guest Linux runtime through the host subprocess service: reports the guest kernel, Alpine version, and whether bash/apk/node/npm/python3 are present. '
@@ -213,13 +234,14 @@ export function apply(ctx) {
 
   register(definition(
     'compat_install',
-    'Submit an already-built plugin tarball or spec to the DSHM host install queue and wait for the host installer result. '
-      + 'This does NOT convert or build anything; use compat_convert first when it exists. Requires confirm:true because installing a plugin runs third-party code.',
+    '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. '
+      + 'Requires confirm:true because installing a plugin runs third-party code; a local install needs a DSHM restart to load.',
     {
       type: 'object',
       properties: {
         spec: { type: 'string', description: 'A file:/absolute-path .tgz produced by the converter, or an npm/GitHub spec.' },
-        profileDir: { type: 'string', description: 'Absolute DSHM profile directory. Omit to let the host choose its profile.' },
+        profileDir: { type: 'string', description: 'Absolute DSHM profile directory. Omit to infer it from this plugin\'s installation path.' },
+        allowLocal: { type: 'boolean', description: 'Allow unpacking a local tarball into the profile. Default true. Set false to force the host install queue.' },
         confirm: { type: 'boolean', description: 'Must be true. The caller confirms that installing this package runs third-party code.' },
       },
       required: ['spec', 'confirm'],
@@ -230,6 +252,14 @@ export function apply(ctx) {
         return { status: 'confirmation-required', message: 'Re-run with confirm:true after reviewing the analyzer report.' }
       }
       try {
+        if (args.allowLocal !== false && isLocalSpec(args.spec)) {
+          const path = args.spec.trim().replace(/^(?:file|link):/i, '')
+          const local = installLocalTarball(path, { profileDir: args.profileDir })
+          recordInstall({ spec: args.spec, at: new Date().toISOString(), ...local })
+          return local.ok
+            ? { status: 'ok', ...local }
+            : { status: 'error', error: { code: 'LOCAL_INSTALL_FAILED', message: local.error ?? 'local install failed' }, ...local }
+        }
         const result = await enqueueInstall(args.spec, { profileDir: args.profileDir, signal: exec?.signal })
         recordInstall({ spec: args.spec, at: new Date().toISOString(), ...result })
         return result

package/lib/doctor.js

@@ -0,0 +1,78 @@
+/**
+ * One-shot DSHM compatibility doctor.
+ *
+ * Collects the facts that decide whether an install can work: whether this is
+ * DSHM, which core is present, which profile owns the plugin, whether the queue
+ * is reachable, and what the guest looks like. It never writes anything.
+ *
+ * @module dshm-compat/doctor
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { inspectCore } from './core.js'
+import { probeGuest } from './guest.js'
+import { resolveProfileDir } from './local-install.js'
+import { dshHome, status } from './state.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 */
+function pluginVersion(file) {
+  const pkg = record(readJson(file))
+  return typeof pkg?.version === 'string' ? pkg.version : undefined
+}
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {NodeJS.ProcessEnv} env
+ */
+export async function runDoctor(ctx, env = process.env) {
+  /** @type {{ name: string, status: 'ok'|'warn'|'error', detail: string }[]} */
+  const checks = []
+  const add = (name, status, detail) => checks.push({ name, status, detail: String(detail) })
+
+  const dshm = env.DSHM_PLATFORM === 'ohos' || typeof env.DSHM_HOME === 'string'
+  add('dshm', dshm ? 'ok' : 'warn', dshm ? `DSHM_HOME=${dshHome(env)}` : 'not running on DSHM; install/queue checks will be limited')
+
+  const core = inspectCore(env)
+  add('core', core.available ? 'ok' : 'warn', core.available ? `DSHM core ${core.version ?? 'unknown'}` : core.reason)
+
+  const profileDir = resolveProfileDir(env)
+  if (profileDir === undefined) {
+    add('profile', 'warn', 'cannot locate the owning profile; pass profileDir to local installs')
+  } else {
+    const manifest = record(readJson(join(profileDir, 'package.json')))
+    const bundles = Array.isArray(manifest?.dsh?.profile?.bundles) ? manifest.dsh.profile.bundles : []
+    add('profile', bundles.includes('dshm-compat') ? 'ok' : 'warn',
+      `${profileDir}; dshm-compat in bundles: ${bundles.includes('dshm-compat')}`)
+  }
+
+  const queue = join(dshHome(env), 'install-queue')
+  add('install-queue', existsSync(queue) ? 'ok' : 'warn', existsSync(queue) ? queue : `${queue} does not exist yet`)
+
+  const state = status(env)
+  add('state', 'ok', `${state.reports.length} report(s), ${state.installs.length} install attempt(s) in ${state.compatDir}`)
+
+  const guest = await probeGuest(ctx, { timeoutMs: 15000 })
+  if (guest.status === 'unavailable') add('guest', 'warn', guest.reason)
+  else if (guest.status === 'ok') add('guest', 'ok', `${guest.run?.uname ?? 'Linux'} / Alpine ${guest.run?.alpine ?? '?'}; bash=${guest.run?.bash} apk=${guest.run?.apk} node=${guest.run?.node}`)
+  else add('guest', 'error', guest.reason ?? guest.stderr ?? 'guest probe failed')
+
+  const overall = checks.some(check => check.status === 'error') ? 'error'
+    : checks.some(check => check.status === 'warn') ? 'warn' : 'ok'
+  return {
+    status: overall,
+    pluginVersion: pluginVersion(new URL('../package.json', import.meta.url)),
+    dshHome: dshHome(env),
+    compatDir: state.compatDir,
+    checks,
+  }
+}

package/lib/fetch.js

@@ -188,7 +188,17 @@ export async function resolveSpec(spec, options = {}) {
     const repo = github[2]
     if (owner.includes('://') || repo.includes('://')) throw new Error(`unsupported GitHub spec: ${raw}`)
     const tarballUrl = `https://api.github.com/repos/${owner}/${repo}/tarball`
-    return { kind: 'github', name: `${owner}/${repo}`, version: '', tarballUrl }
+    return {
+      kind: 'github',
+      name: `${owner}/${repo}`,
+      version: '',
+      tarballUrl,
+      fallbackUrls: [
+        `https://codeload.github.com/${owner}/${repo}/tar.gz/HEAD`,
+        `https://codeload.github.com/${owner}/${repo}/tar.gz/refs/heads/main`,
+        `https://codeload.github.com/${owner}/${repo}/tar.gz/refs/heads/master`,
+      ],
+    }
   }
 
   // Direct tarball URL.
@@ -229,9 +239,18 @@ export async function resolveSpec(spec, options = {}) {
  */
 export async function loadArchive(resolved, options = {}) {
   if (resolved.buffer !== undefined) return resolved.buffer
-  return downloadBuffer(resolved.tarballUrl, {
-    maxBytes: options.maxBytes,
-    signal: options.signal,
-    headers: resolved.kind === 'github' ? { accept: 'application/vnd.github+json' } : {},
-  })
+  const urls = [resolved.tarballUrl, ...(Array.isArray(resolved.fallbackUrls) ? resolved.fallbackUrls : [])]
+  let lastError
+  for (const url of urls) {
+    try {
+      return await downloadBuffer(url, {
+        maxBytes: options.maxBytes,
+        signal: options.signal,
+        headers: resolved.kind === 'github' ? { accept: 'application/vnd.github+json' } : {},
+      })
+    } catch (error) {
+      lastError = error
+    }
+  }
+  throw lastError ?? new Error(`no archive URL for ${resolved.name ?? 'spec'}`)
 }

package/lib/local-install.js

@@ -0,0 +1,179 @@
+/**
+ * Manual profile installation for converted artifacts.
+ *
+ * DSHM's host installer accepts npm names and GitHub repositories, but rejects
+ * local tarballs, `file:` and `http://` specs. A converted package has to land
+ * in the profile another way: unpack it under `<profile>/node_modules/<name>`,
+ * record the dependency, and append the bundle so the next boot composes its
+ * patch. This mirrors the manual installation the DSHM agent performed for
+ * `dshm-compat` itself.
+ *
+ * @module dshm-compat/local-install
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { dshHome } from './state.js'
+import { extractTar } from './tar.js'
+import { validateTarball } from './validate.js'
+
+/** @param {unknown} value */
+function record(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined
+}
+
+/** @param {string} file */
+function readJson(file) {
+  return JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, ''))
+}
+
+/** @param {string} file @param {unknown} value */
+function writeJsonAtomic(file, value) {
+  const text = `${JSON.stringify(value, null, 2)}\n`
+  const temporary = `${file}.tmp-${process.pid}-${Date.now()}`
+  writeFileSync(temporary, text, 'utf8')
+  try { renameSync(temporary, file) } catch {
+    writeFileSync(file, text, 'utf8')
+    try { rmSync(temporary, { force: true }) } catch { /* best effort */ }
+  }
+}
+
+/** @param {string} candidate */
+function looksLikeProfile(candidate) {
+  return existsSync(join(candidate, 'package.json'))
+}
+
+/** @param {NodeJS.ProcessEnv} env */
+function profileFromModule() {
+  let current = dirname(fileURLToPath(import.meta.url))
+  for (let depth = 0; depth < 8; depth += 1) {
+    if (basename(current) === 'node_modules') return dirname(current)
+    const parent = dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return undefined
+}
+
+/**
+ * Resolve the profile that owns this plugin.
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string | undefined}
+ */
+export function resolveProfileDir(env = process.env) {
+  if (typeof env.DSH_PROFILE_DIR === 'string' && looksLikeProfile(env.DSH_PROFILE_DIR)) return env.DSH_PROFILE_DIR
+  const fromModule = profileFromModule()
+  if (fromModule !== undefined && looksLikeProfile(fromModule)) return fromModule
+  const name = env.DSH_PROFILE
+  if (typeof name === 'string' && name !== '') {
+    const candidate = join(dshHome(env), 'profiles', name)
+    if (looksLikeProfile(candidate)) return candidate
+  }
+  return undefined
+}
+
+/** @param {string} spec */
+export function isLocalSpec(spec) {
+  if (typeof spec !== 'string' || spec.trim() === '') return false
+  const raw = spec.trim()
+  if (/^(?:file|link):/i.test(raw)) return true
+  if (isAbsolute(raw)) return true
+  return /\.(?:tgz|tar\.gz)(?:[?#].*)?$/i.test(raw)
+}
+
+/** @param {string} target @param {import('./tar.js').TarEntry[]} entries */
+function writeEntries(target, entries) {
+  rmSync(target, { recursive: true, force: true })
+  mkdirSync(target, { recursive: true })
+  for (const entry of entries) {
+    if (entry.type !== 'file') continue
+    const relative = entry.path.replace(/^package\//, '')
+    if (relative === '' || relative.startsWith('/') || relative.split('/').includes('..')) continue
+    const file = join(target, relative)
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, entry.data, { mode: entry.mode === 0 ? 0o644 : entry.mode & 0o777 })
+  }
+}
+
+/**
+ * @param {string} tarball
+ * @param {{ profileDir?: string, env?: NodeJS.ProcessEnv }} [options]
+ */
+export function installLocalTarball(tarball, options = {}) {
+  const env = options.env ?? process.env
+  if (typeof tarball !== 'string' || !existsSync(tarball)) {
+    return { ok: false, error: `tarball not found: ${String(tarball)}` }
+  }
+  const validation = validateTarball(tarball)
+  if (!validation.ok) return { ok: false, error: `converted tarball is invalid: ${validation.errors.join('; ')}` }
+
+  const profileDir = typeof options.profileDir === 'string' && options.profileDir !== ''
+    ? resolve(options.profileDir)
+    : resolveProfileDir(env)
+  if (profileDir === undefined || !looksLikeProfile(profileDir)) {
+    return { ok: false, error: 'cannot locate the DSH profile that owns this plugin; pass profileDir explicitly' }
+  }
+
+  const { entries } = extractTar(readFileSync(tarball))
+  const packageEntry = entries.find(entry => entry.path === 'package/package.json')
+  if (packageEntry?.data === undefined) return { ok: false, error: 'converted tarball has no package/package.json' }
+  const pkg = record(JSON.parse(packageEntry.data.toString('utf8')))
+  const name = typeof pkg?.name === 'string' ? pkg.name : undefined
+  const version = typeof pkg?.version === 'string' ? pkg.version : '0.0.0'
+  if (name === undefined || !/^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/i.test(name)) {
+    return { ok: false, error: 'converted tarball has no valid package name' }
+  }
+
+  const destination = join(profileDir, 'node_modules', ...name.split('/'))
+  const manifestPath = join(profileDir, 'package.json')
+  const manifest = readJson(manifestPath)
+  if (record(manifest) === undefined) return { ok: false, error: `profile manifest is not an object: ${manifestPath}` }
+
+  const staging = `${destination}.staging-${process.pid}-${Date.now()}`
+  const backup = `${destination}.backup-${process.pid}-${Date.now()}`
+  let movedOld = false
+  try {
+    writeEntries(staging, entries)
+    if (existsSync(destination)) {
+      renameSync(destination, backup)
+      movedOld = true
+    }
+    renameSync(staging, destination)
+
+    const dependencies = record(manifest.dependencies) ?? {}
+    dependencies[name] = version
+    manifest.dependencies = dependencies
+    const dsh = record(manifest.dsh) ?? {}
+    const profile = record(dsh.profile) ?? {}
+    const bundles = Array.isArray(profile.bundles) ? profile.bundles.filter(item => typeof item === 'string') : []
+    if (!bundles.includes(name)) bundles.push(name)
+    profile.bundles = bundles
+    dsh.profile = profile
+    manifest.dsh = dsh
+    writeJsonAtomic(manifestPath, manifest)
+
+    if (movedOld) {
+      try { rmSync(backup, { recursive: true, force: true }) } catch { /* keep the backup if it is locked */ }
+    }
+    return {
+      ok: true,
+      method: 'local-profile',
+      profileDir,
+      name,
+      version,
+      destination,
+      restartRequired: true,
+      warnings: validation.warnings,
+    }
+  } catch (error) {
+    try { rmSync(staging, { recursive: true, force: true }) } catch { /* staging may be gone */ }
+    try {
+      if (existsSync(destination)) rmSync(destination, { recursive: true, force: true })
+      if (movedOld && existsSync(backup)) renameSync(backup, destination)
+    } catch { /* report the original error; recovery is best effort */ }
+    return {
+      ok: false,
+      error: `local install failed: ${String(error?.message ?? error)}${movedOld ? '; previous files restored' : ''}`,
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dshm-compat",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Analyze and convert DSH plugins that cannot be installed or run on HarmonyOS DSHM.",
   "type": "module",
   "main": "index.js",
@@ -29,6 +29,7 @@
     "icon.svg",
     "README.md",
     "INSTALL.md",
+    "CHANGELOG.md",
     "docs/*.md"
   ],
   "engines": {