dshm-compat 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 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

@@ -5,15 +5,26 @@ 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:
-
-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**.
+first), or push this directory to a GitHub repository.
+
+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.1` 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
 

package/README.md

@@ -5,8 +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, and the DSHM install-queue transport:
+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,12 @@ 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_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/index.js

@@ -12,6 +12,7 @@ import { scan } from './lib/batch.js'
 import { convert } from './lib/convert.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 +48,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 +152,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 +168,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) {
@@ -213,13 +224,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 +242,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/local-install.js

@@ -0,0 +1,155 @@
+/**
+ * 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('/'))
+  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,
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dshm-compat",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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": {