dshm-compat 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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

package/INSTALL.md

@@ -1,6 +1,6 @@
 # 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)
@@ -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.1` in its bash tool (the
+- 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
@@ -28,7 +28,7 @@ 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.
@@ -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.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
@@ -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.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,10 +5,10 @@ them through the least invasive strategy that can work.
 
 ## Current phase
 
-0.1.1 fixes DSHM tool-result validation and adds local-tarball installation.
-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:
+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.
@@ -24,6 +24,8 @@ fallback for artifacts the host queue rejects:
 - `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_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

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,6 +10,7 @@
 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'
@@ -189,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. '

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

@@ -125,31 +125,55 @@ export function installLocalTarball(tarball, options = {}) {
   }
 
   const destination = join(profileDir, 'node_modules', ...name.split('/'))
-  writeEntries(destination, entries)
-
   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 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)
 
-  return {
-    ok: true,
-    method: 'local-profile',
-    profileDir,
-    name,
-    version,
-    destination,
-    restartRequired: true,
-    warnings: validation.warnings,
+  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.1",
+  "version": "0.1.2",
   "description": "Analyze and convert DSH plugins that cannot be installed or run on HarmonyOS DSHM.",
   "type": "module",
   "main": "index.js",