dshm-compat 0.0.0-stage → 0.1.0

package/index.js

@@ -0,0 +1,243 @@
+/**
+ * dshm-compat host half.
+ *
+ * Phase 1 exposes the read-only compatibility analyzer and the DSHM install
+ * queue transport. The converter and guest sidecar are added behind the same
+ * service/tool surface in later phases.
+ *
+ * @module dshm-compat
+ */
+import { analyze } from './lib/analyze.js'
+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 { buildPlan } from './lib/plan.js'
+import { recordInstall, recordReport, status } from './lib/state.js'
+
+export const name = 'dshm-compat'
+export const inject = ['tools']
+
+const OUTPUT = { type: 'object', additionalProperties: true }
+const RESULT_NOTE = ' Returns a JSON result; failures are values with status:"error", not thrown.'
+
+/** @param {unknown} value */
+function errorResult(error) {
+  return {
+    status: 'error',
+    error: {
+      code: typeof error?.code === 'string' ? error.code : 'COMPAT_ERROR',
+      message: String(error?.message ?? error),
+    },
+  }
+}
+
+/** @param {unknown} _args @param {unknown} value */
+function renderJson(_args, value) {
+  let text
+  try { text = JSON.stringify(value, null, 2) } catch { text = String(value) }
+  if (text.length > 60000) text = `${text.slice(0, 60000)}\n... [truncated]`
+  return [{ type: 'text', text }]
+}
+
+/** @param {string} name @param {string} description @param {Record<string, unknown>} parameters @param {(args: any, exec: any) => Promise<unknown>} execute */
+function definition(name, description, parameters, execute) {
+  return {
+    name,
+    description: description + RESULT_NOTE,
+    parameters,
+    output: { schema: OUTPUT, render: renderJson },
+    execute,
+  }
+}
+
+export function apply(ctx) {
+  const register = (tool, label) => {
+    ctx.effect(() => ctx.tools.register(tool), `dshm-compat: ${label}`)
+  }
+
+  register(definition(
+    'compat_analyze',
+    'Download one DSH plugin package (npm name[@version], a GitHub repository URL, or a local .tgz) and classify why it may not install or run on HarmonyOS DSHM. '
+      + 'Read-only: it does not execute install scripts and does not modify any profile. '
+      + 'The report names a strategy (S0 pure JS/TS, S1 known native substitute, S2 guest Alpine sidecar, S3 WASM/remote, S4 unsupported), the evidence, and the next action.',
+    {
+      type: 'object',
+      properties: {
+        spec: { type: 'string', description: 'npm package name with optional @version, a GitHub repository URL, or an absolute/relative .tgz path.' },
+        textScan: { type: 'boolean', description: 'Scan JavaScript text for platform/Electron/child_process references. Default true; set false for a fast structural report.' },
+      },
+      required: ['spec'],
+      additionalProperties: false,
+    },
+    async (args, exec) => {
+      try {
+        if (typeof args?.spec !== 'string' || args.spec.trim() === '') throw Object.assign(new Error('spec is required'), { code: 'INVALID_SPEC' })
+        const report = await analyze(args.spec.trim(), { textScan: args.textScan !== false, signal: exec?.signal })
+        const entry = recordReport(report)
+        return { status: 'ok', entry, report }
+      } catch (error) {
+        return errorResult(error)
+      }
+    },
+  ), 'compat_analyze')
+
+  register(definition(
+    'compat_plan',
+    'Analyze one plugin and return a concrete conversion plan without changing anything: manifest rewrite steps for S0, dependency substitutions for S1, guest provisioning and native build targets for S2, or an explicit unsupported result for S4.',
+    {
+      type: 'object',
+      properties: {
+        spec: { type: 'string', description: 'npm package name with optional @version, a GitHub repository URL, or an absolute/relative .tgz path.' },
+      },
+      required: ['spec'],
+      additionalProperties: false,
+    },
+    async (args, exec) => {
+      try {
+        if (typeof args?.spec !== 'string' || args.spec.trim() === '') throw Object.assign(new Error('spec is required'), { code: 'INVALID_SPEC' })
+        const report = await analyze(args.spec.trim(), { textScan: true, signal: exec?.signal })
+        recordReport(report)
+        return { status: 'ok', plan: buildPlan(report), report }
+      } catch (error) {
+        return errorResult(error)
+      }
+    },
+  ), 'compat_plan')
+
+  register(definition(
+    'compat_scan',
+    'Analyze up to 50 plugin specs in parallel (3 at a time) and return a per-strategy compatibility table. Use this to triage a market list before converting individual packages; full reports are stored under $DSH_HOME/dshm-compat/reports and summarized here.',
+    {
+      type: 'object',
+      properties: {
+        specs: { type: 'array', items: { type: 'string' }, description: 'npm names, GitHub URLs, or local .tgz paths. At most 50; duplicates are removed.' },
+        textScan: { type: 'boolean', description: 'Scan JavaScript text too. Default false for batch speed.' },
+      },
+      required: ['specs'],
+      additionalProperties: false,
+    },
+    async (args, exec) => {
+      try {
+        const result = await scan(args?.specs, { textScan: args?.textScan === true, signal: exec?.signal })
+        for (const item of result.items) if (item.ok && item.report !== undefined) recordReport(item.report)
+        return {
+          status: 'ok',
+          counts: result.counts,
+          items: result.items.map(({ report: _report, ...item }) => item),
+        }
+      } catch (error) {
+        return errorResult(error)
+      }
+    },
+  ), 'compat_scan')
+
+  register(definition(
+    'compat_convert',
+    'Convert one S0 (pure JS/TS) plugin into a DSHM-installable tarball: remove foreign os/cpu gates and install lifecycle scripts, normalize the client platform to web, and repack. '
+      + 'It does not execute install scripts and does not bundle runtime dependencies yet. S1/S2/S3/S4 reports are returned with the next action instead of pretending to convert.',
+    {
+      type: 'object',
+      properties: {
+        spec: { type: 'string', description: 'npm package name with optional @version, a GitHub repository URL, or an absolute/relative .tgz path.' },
+        install: { type: 'boolean', description: 'When true, submit the converted tarball to the DSHM install queue after a successful conversion.' },
+        profileDir: { type: 'string', description: 'Absolute DSHM profile directory for install:true. Omit to let the host choose.' },
+        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.' },
+      },
+      required: ['spec'],
+      additionalProperties: false,
+    },
+    async (args, exec) => {
+      try {
+        if (typeof args?.spec !== 'string' || args.spec.trim() === '') throw Object.assign(new Error('spec is required'), { code: 'INVALID_SPEC' })
+        const report = await analyze(args.spec.trim(), { textScan: false, signal: exec?.signal })
+        const result = await convert(args.spec.trim(), { report, signal: exec?.signal, vendor: args.vendor !== false, workerPath: args.workerPath })
+        if (result.status !== 'ok') return result
+        recordReport({ ...report, convertedAt: new Date().toISOString(), tarball: result.tarball })
+        if (args.install !== true) return result
+        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 })
+        recordInstall({ spec: args.spec, tarball: result.tarball, at: new Date().toISOString(), ...installed })
+        return { ...result, install: installed }
+      } catch (error) {
+        return errorResult(error)
+      }
+    },
+  ), 'compat_convert')
+
+  register(definition(
+    'compat_status',
+    'Show the compatibility analyzer reports and install attempts stored under $DSH_HOME/dshm-compat, plus whether the current host looks like DSHM.',
+    { type: 'object', properties: {}, additionalProperties: false },
+    async () => {
+      try { return { status: 'ok', ...status() } } catch (error) { return errorResult(error) }
+    },
+  ), 'compat_status')
+
+  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. '
+      + 'Read-only; it does not install packages or start a VM explicitly (DSHM may route bash -c to its guest).',
+    { type: 'object', properties: {}, additionalProperties: false },
+    async (_args, exec) => {
+      try { return { status: 'ok', ...(await probeGuest(ctx, { signal: exec?.signal })) } } catch (error) { return errorResult(error) }
+    },
+  ), 'compat_guest_probe')
+
+  register(definition(
+    'compat_guest_provision',
+    'Install a reviewed allowlist of Alpine packages in the DSHM guest (bash, nodejs, npm, python3, build-base, linux-headers, git, ffmpeg). '
+      + 'Requires confirm:true because it modifies the guest root filesystem. It reports the exact apk output; no success is assumed when the guest has no network.',
+    {
+      type: 'object',
+      properties: {
+        packages: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Subset of the allowlist. Omit for bash, nodejs, npm, python3, build-base, linux-headers.',
+        },
+        confirm: { type: 'boolean', description: 'Must be true to modify the guest root filesystem.' },
+      },
+      required: ['confirm'],
+      additionalProperties: false,
+    },
+    async (args, exec) => {
+      if (args?.confirm !== true) return { status: 'confirmation-required', message: 'Re-run with confirm:true after reviewing the package list.' }
+      try { return { status: 'ok', ...(await provisionGuest(ctx, args.packages, { signal: exec?.signal })) } } catch (error) { return errorResult(error) }
+    },
+  ), 'compat_guest_provision')
+
+  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.',
+    {
+      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.' },
+        confirm: { type: 'boolean', description: 'Must be true. The caller confirms that installing this package runs third-party code.' },
+      },
+      required: ['spec', 'confirm'],
+      additionalProperties: false,
+    },
+    async (args, exec) => {
+      if (args?.confirm !== true) {
+        return { status: 'confirmation-required', message: 'Re-run with confirm:true after reviewing the analyzer report.' }
+      }
+      try {
+        const result = await enqueueInstall(args.spec, { profileDir: args.profileDir, signal: exec?.signal })
+        recordInstall({ spec: args.spec, at: new Date().toISOString(), ...result })
+        return result
+      } catch (error) {
+        return errorResult(error)
+      }
+    },
+  ), 'compat_install')
+
+  ctx.logger?.info?.('dshm-compat: analyzer ready (S0-S4); conversion and guest sidecar are next')
+}

package/lib/analyze.js

@@ -0,0 +1,381 @@
+/**
+ * Compatibility analyzer for DSH plugins aimed at HarmonyOS DSHM.
+ *
+ * The analyzer is deliberately read-only: it downloads a package archive,
+ * inspects its files and manifests, and returns a classification plus the next
+ * action. No install script is executed and nothing is written into a profile.
+ *
+ * Strategy codes:
+ *   S0 - pure JS/TS: code-level conversion on the host
+ *   S1 - known native dependencies with an OHOS/JS substitute
+ *   S2 - native binaries or shell commands: guest Alpine sidecar
+ *   S3 - source-available native: WASM or remote build
+ *   S4 - unsupported: e.g. a win32-only binary with no source
+ *
+ * @module dshm-compat/analyze
+ */
+import { createHash } from 'node:crypto'
+import { checkDependencies } from './core.js'
+import { lookupPackageRule } from './rules.js'
+import { findRootPrefix, extractTar } from './tar.js'
+import { loadArchive, resolveSpec } from './fetch.js'
+
+/** Runtime dependencies that are native or install a native payload. */
+const KNOWN_NATIVE = {
+  'sharp': { ohos: '@ohos-ports/sharp', note: 'DSHM already ships an OpenHarmony port' },
+  'node-pty': { ohos: '@ohos-ports/node-pty', note: 'DSHM already ships an OpenHarmony port' },
+  'koffi': { ohos: '@ohos-ports/koffi', note: 'DSHM already ships an OpenHarmony port' },
+  'better-sqlite3': { js: 'node:sqlite', note: 'Node 24 ships node:sqlite; behavior differs' },
+  'sqlite3': { js: 'node:sqlite', note: 'Node 24 ships node:sqlite; behavior differs' },
+  'canvas': { js: '@napi-rs/canvas / pure JS fallback', note: 'no OHOS build in the package' },
+  'bcrypt': { js: 'bcryptjs', note: 'pure-JS replacement' },
+  'argon2': { js: 'hash-wasm', note: 'WASM replacement' },
+  'esbuild': { js: 'esbuild-wasm', note: 'WASM replacement' },
+  'node-gyp': { build: true, note: 'requires a C/C++ toolchain' },
+  'prebuild-install': { build: true, note: 'downloads a prebuilt native binary' },
+  'node-pre-gyp': { build: true, note: 'downloads or builds a native binary' },
+  '@napi-rs/canvas': { js: 'WASM/JS fallback', note: 'native N-API package' },
+}
+
+const NATIVE_EXTENSIONS = new Set(['.node', '.so', '.dll', '.dylib', '.exe', '.wasm'])
+const TEXT_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.tsx', '.jsx', '.json'])
+const SCAN_FILE_LIMIT = 512 * 1024
+const SCAN_TOTAL_LIMIT = 32 * 1024 * 1024
+const SCAN_SAMPLE_LIMIT = 5
+
+/** @param {string} path */
+function extname(path) {
+  const base = path.slice(path.lastIndexOf('/') + 1)
+  const dot = base.lastIndexOf('.')
+  return dot <= 0 ? '' : base.slice(dot).toLowerCase()
+}
+
+/** @param {unknown} value */
+function record(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined
+}
+
+/** @param {unknown} value */
+function stringArray(value) {
+  return Array.isArray(value) ? value.filter(item => typeof item === 'string') : []
+}
+
+/** @param {string} text @param {RegExp} pattern */
+function countMatches(text, pattern) {
+  const matches = text.match(pattern)
+  return matches === null ? 0 : matches.length
+}
+
+/** @param {{ path: string, data?: Buffer, size: number }} file */
+function isProbablyText(file) {
+  if (file.data === undefined) return false
+  const probe = file.data.subarray(0, Math.min(file.data.length, 4096))
+  return !probe.includes(0)
+}
+
+/**
+ * Pick the package root: an archive-level top directory is stripped by the tar
+ * reader, then the shallowest package.json wins (handles monorepo subpackages).
+ *
+ * @param {import('./tar.js').TarEntry[]} entries
+ */
+function selectPackageRoot(entries) {
+  const files = entries.filter(entry => entry.type === 'file')
+  const candidates = files
+    .filter(entry => 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)
+  if (candidates.length === 0) return { dir: '', packageFile: undefined }
+  const root = candidates[0]
+  return { dir: root.dir === '' ? '' : `${root.dir}/`, packageFile: `${root.dir}/package.json` }
+}
+
+/**
+ * @param {string} spec
+ * @param {{ registry?: string, signal?: AbortSignal, maxBytes?: number, textScan?: boolean }} [options]
+ */
+export async function analyze(spec, options = {}) {
+  const resolved = await resolveSpec(spec, { registry: options.registry, signal: options.signal })
+  const archive = await loadArchive(resolved, { maxBytes: options.maxBytes, signal: options.signal })
+  const { entries, totalBytes, truncated } = extractTar(archive)
+  const archivePrefix = findRootPrefix(entries)
+  const topEntries = entries.map(entry => ({
+    ...entry,
+    path: archivePrefix !== '' && entry.path.startsWith(archivePrefix) ? entry.path.slice(archivePrefix.length) : entry.path,
+  }))
+  const { dir, packageFile } = selectPackageRoot(topEntries)
+  const files = topEntries
+    .filter(entry => entry.type === 'file' && entry.path.startsWith(dir))
+    .map(entry => ({ ...entry, path: entry.path.slice(dir.length) }))
+
+  /** @type {Buffer | undefined} */
+  let packageText
+  const packageEntry = packageFile === undefined ? undefined : files.find(file => file.path === 'package.json')
+  if (packageEntry?.data !== undefined) packageText = packageEntry.data
+  let packageJson
+  let packageError
+  if (packageText !== undefined) {
+    try { packageJson = JSON.parse(packageText.toString('utf8')) } catch (error) { packageError = String(error?.message ?? error) }
+  }
+
+  const manifestEntry = files.find(file => file.path === 'dsh-plugin.json')
+  let manifest
+  let manifestError
+  if (manifestEntry?.data !== undefined) {
+    try { manifest = JSON.parse(manifestEntry.data.toString('utf8')) } catch (error) { manifestError = String(error?.message ?? error) }
+  }
+
+  const pkg = record(packageJson)
+  const dsh = pkg === undefined ? undefined : record(pkg.dsh)
+  const scripts = pkg === undefined ? undefined : record(pkg.scripts)
+  const dependencies = new Set([
+    ...Object.keys(record(pkg?.dependencies) ?? {}),
+    ...Object.keys(record(pkg?.optionalDependencies) ?? {}),
+    ...Object.keys(record(pkg?.peerDependencies) ?? {}),
+  ])
+  const installScripts = {}
+  for (const name of ['preinstall', 'install', 'postinstall', 'prepare']) {
+    if (typeof scripts?.[name] === 'string') installScripts[name] = scripts[name]
+  }
+
+  const nativeFiles = []
+  const packageFiles = []
+  let scannedBytes = 0
+  const scan = {
+    files: 0,
+    truncated: false,
+    processPlatform: 0,
+    win32: 0,
+    darwin: 0,
+    linux: 0,
+    childProcess: 0,
+    spawn: 0,
+    exec: 0,
+    electron: 0,
+    browserWindow: 0,
+    dlopen: 0,
+    samples: { processPlatform: [], win32: [], childProcess: [], electron: [] },
+  }
+
+  for (const file of files) {
+    const extension = extname(file.path)
+    if (NATIVE_EXTENSIONS.has(extension) || file.path.endsWith('/binding.gyp') || file.path.startsWith('prebuilds/')) {
+      nativeFiles.push({ path: file.path, size: file.size, extension: extension || 'gyp' })
+    }
+    if (extension === '.json' && file.path !== 'package.json' && file.path !== 'dsh-plugin.json') {
+      packageFiles.push(file.path)
+    }
+    if (options.textScan === false) continue
+    if (!TEXT_EXTENSIONS.has(extension) || file.data === undefined) continue
+    if (file.size > SCAN_FILE_LIMIT || scannedBytes + file.size > SCAN_TOTAL_LIMIT) { scan.truncated = true; continue }
+    if (!isProbablyText(file)) continue
+    const text = file.data.toString('utf8')
+    scannedBytes += file.size
+    scan.files += 1
+    for (const [key, pattern] of [
+      ['processPlatform', /process\.platform/g],
+      ['win32', /\bwin32\b/g],
+      ['darwin', /\bdarwin\b/g],
+      ['linux', /\blinux\b/g],
+      ['childProcess', /child_process/g],
+      ['spawn', /\.spawn\s*\(/g],
+      ['exec', /\.exec\s*\(/g],
+      ['electron', /\belectron\b/g],
+      ['browserWindow', /BrowserWindow/g],
+      ['dlopen', /process\.dlopen|\.node['"]/g],
+    ]) {
+      const count = countMatches(text, pattern)
+      if (count === 0) continue
+      scan[key] += count
+      if (scan.samples[key] !== undefined && scan.samples[key].length < SCAN_SAMPLE_LIMIT) scan.samples[key].push(file.path)
+    }
+  }
+
+  const nativeDeps = [...dependencies]
+    .filter(name => KNOWN_NATIVE[name] !== undefined)
+    .map(name => ({ name, ...KNOWN_NATIVE[name] }))
+  const dependencyCheck = checkDependencies(pkg, options.env ?? process.env)
+  const unknownNativeDeps = nativeDeps.filter(dep => dep.ohos === undefined && dep.js === undefined && dep.build !== true)
+  const platformBlocked = pkg !== undefined && (
+    (Array.isArray(pkg.os) && !pkg.os.includes('linux') && !pkg.os.includes('openharmony'))
+    || (Array.isArray(pkg.cpu) && !pkg.cpu.includes('arm64'))
+  )
+  const hasDsh = dsh !== undefined && (record(dsh.bundle) !== undefined || record(dsh.client) !== undefined)
+  const client = record(dsh?.client)
+  const targets = []
+  if (manifest !== undefined && manifest !== null && typeof manifest === 'object' && Array.isArray(manifest.contributes?.['x-components'])) {
+    for (const component of manifest.contributes['x-components']) {
+      if (record(component) === undefined) continue
+      targets.push({
+        id: typeof component.id === 'string' ? component.id : undefined,
+        platforms: stringArray(component.platforms),
+        architectures: stringArray(component.architectures),
+        targets: stringArray(component.targets),
+      })
+    }
+  }
+
+  const hasWin32OnlyPayload = nativeFiles.length > 0
+    && nativeFiles.every(file => /(?:^|\/)win32-|\.exe$|\.dll$/i.test(file.path))
+  const hasNativeSource = files.some(file => (
+    file.path === 'native/Cargo.toml'
+    || file.path.endsWith('/Cargo.toml')
+    || file.path === 'binding.gyp'
+    || /(?:^|\/)native\/src\//.test(file.path)
+    || /(?:^|\/)src\/.+\.(?:c|cc|cpp|h|hpp|rs)$/.test(file.path)
+  ))
+  const hasLifecycle = ['preinstall', 'install', 'postinstall'].some(name => typeof scripts?.[name] === 'string')
+  const entryCandidates = [
+    typeof pkg?.main === 'string' ? pkg.main : undefined,
+    typeof dsh?.bundle?.patch === 'string' ? dsh.bundle.patch : undefined,
+    typeof pkg?.exports === 'object' && pkg.exports !== null ? pkg.exports['./client'] : undefined,
+  ].filter(value => typeof value === 'string').map(value => value.replace(/^\.\//, ''))
+  const missingEntries = entryCandidates.filter(entry => !files.some(file => file.path === entry))
+  const prepareNeedsBuild = typeof scripts?.prepare === 'string' && missingEntries.length > 0
+  const needsBuild = hasLifecycle || prepareNeedsBuild
+  const electronSurface = scan.electron > 0 || scan.browserWindow > 0
+
+  let strategy
+  let confidence = 'medium'
+  const reasons = []
+  const next = []
+
+  if (hasWin32OnlyPayload && !hasNativeSource) {
+    strategy = 'S4'
+    confidence = 'high'
+    reasons.push('the archive carries only win32 payloads and no C/C++/Rust source to rebuild')
+    next.push('ask the plugin author for source or a linux-arm64 build')
+  } else if (nativeFiles.length > 0 || unknownNativeDeps.length > 0 || electronSurface) {
+    strategy = 'S2'
+    confidence = 'medium'
+    if (nativeFiles.length > 0) reasons.push(`${nativeFiles.length} native file(s) need a linux-arm64 runtime outside the DSHM host process`)
+    if (unknownNativeDeps.length > 0) reasons.push(`unrecognized native dependencies: ${unknownNativeDeps.map(dep => dep.name).join(', ')}`)
+    if (Object.keys(installScripts).length > 0) reasons.push(`install scripts: ${Object.keys(installScripts).join(', ')}`)
+    if (electronSurface) reasons.push(`Electron API surface detected (${scan.electron} reference(s)); needs a shim or a sidecar UI`)
+    next.push('run the plugin in the Alpine guest sidecar and expose its tools through RPC')
+    if (electronSurface) next.push('apply the Electron API shim for app/shell/dialog/clipboard/ipc')
+  } else if (nativeDeps.length > 0) {
+    strategy = 'S1'
+    confidence = 'medium'
+    reasons.push(`native dependencies have known substitutes: ${nativeDeps.map(dep => dep.name).join(', ')}`)
+    next.push(`substitute ${nativeDeps.map(dep => `${dep.name} -> ${dep.ohos ?? dep.js}`).join(', ')}`)
+  } else if (needsBuild) {
+    strategy = 'S0'
+    confidence = 'medium'
+    reasons.push(prepareNeedsBuild
+      ? `prepare script is required because built entry files are missing: ${missingEntries.join(', ')}`
+      : `install lifecycle script(s): ${Object.keys(installScripts).join(', ')}`)
+    next.push('run the pure-JS build recipe in a controlled Node worker, then bundle and pack')
+  } else {
+    strategy = 'S0'
+    confidence = 'high'
+    reasons.push('no blocking native files, native dependencies, or install lifecycle scripts found')
+    if (typeof scripts?.prepare === 'string') reasons.push('prepare script is present but its built entry files already exist; a registry tarball does not need to run it')
+    next.push('rewrite package.json, bundle host/client code, pack and install')
+  }
+
+  if (platformBlocked) {
+    reasons.push('package.json os/cpu excludes a Linux/arm64 target; the manifest must be rewritten')
+    if (strategy === 'S0') confidence = 'medium'
+  }
+  if (dependencyCheck.missing.length > 0) {
+    reasons.push(`runtime dependencies not present in the DSHM core: ${dependencyCheck.missing.slice(0, 30).join(', ')}; vendor or bundle them before install`)
+    if (strategy === 'S0') confidence = 'medium'
+  }
+  if (dependencyCheck.core.available === false && Object.keys(dependencyCheck.dependencies).length > 0) {
+    reasons.push(`DSHM core inventory unavailable (${dependencyCheck.core.reason}); dependency availability is unverified`)
+  }
+  if (unknownNativeDeps.length > 0) {
+    reasons.push(`unrecognized native dependency: ${unknownNativeDeps.map(dep => dep.name).join(', ')}`)
+    confidence = 'low'
+  }
+  if (truncated) {
+    reasons.push('archive was truncated by the safety limit; the report may be incomplete')
+    confidence = 'low'
+  }
+  if (packageError !== undefined) {
+    reasons.push(`package.json could not be parsed: ${packageError}`)
+    confidence = 'low'
+  }
+
+  const rule = lookupPackageRule(typeof pkg?.name === 'string' ? pkg.name : undefined, options.env ?? process.env)
+  if (rule !== undefined) {
+    strategy = rule.strategy
+    confidence = 'high'
+    reasons.push(`package rule: ${rule.reason}`)
+    for (const step of rule.next) if (!next.includes(step)) next.push(step)
+  }
+
+  const fingerprint = createHash('sha256')
+    .update(`${resolved.kind}\0${resolved.name}\0${resolved.version}\0${archive.length}`)
+    .digest('hex')
+
+  return {
+    spec: String(spec),
+    fingerprint,
+    resolved: {
+      kind: resolved.kind,
+      name: resolved.name,
+      requested: resolved.requested,
+      version: resolved.version,
+      approximated: resolved.approximated ?? false,
+      tarball: resolved.tarballUrl,
+      archiveBytes: archive.length,
+    },
+    package: pkg === undefined ? undefined : {
+      name: pkg.name,
+      version: pkg.version,
+      description: pkg.description,
+      type: pkg.type,
+      main: pkg.main,
+      os: pkg.os,
+      cpu: pkg.cpu,
+      scripts,
+      dependencies: pkg.dependencies,
+      optionalDependencies: pkg.optionalDependencies,
+      peerDependencies: pkg.peerDependencies,
+      dsh,
+      bin: pkg.bin,
+    },
+    manifest: manifest === undefined ? undefined : {
+      id: manifest.id,
+      name: manifest.name,
+      version: manifest.version,
+      targets,
+    },
+    files: {
+      count: files.length,
+      totalBytes: files.reduce((sum, file) => sum + file.size, 0),
+      native: nativeFiles.slice(0, 100),
+      json: packageFiles.slice(0, 50),
+      truncated,
+    },
+    signals: {
+      hasDsh,
+      hostEntry: hasDsh ? (typeof dsh?.bundle?.patch === 'string' ? dsh.bundle.patch : 'inferred from main') : undefined,
+      client: client === undefined ? undefined : {
+        platform: client.platform,
+        inject: stringArray(client.inject),
+        external: stringArray(client.external),
+      },
+      nativeDeps,
+      unknownNativeDeps: unknownNativeDeps.map(dep => dep.name),
+      dependencies: {
+        core: dependencyCheck.core,
+        present: dependencyCheck.present.slice(0, 100),
+        missing: dependencyCheck.missing.slice(0, 100),
+        optionalMissing: (dependencyCheck.optionalMissing ?? []).slice(0, 100),
+        unknown: dependencyCheck.unknown,
+      },
+      installScripts,
+      platformBlocked,
+      scan,
+      electronSurface,
+    },
+    strategy,
+    confidence,
+    rule: rule === undefined ? undefined : { strategy: rule.strategy, reason: rule.reason, nativeBuild: rule.nativeBuild },
+    reasons,
+    next,
+  }
+}

package/lib/batch.js

@@ -0,0 +1,60 @@
+/**
+ * Bounded batch analysis.
+ *
+ * Scanning a market list is the only practical way to answer "which of these
+ * can be converted"; doing it serially would be too slow and unbounded
+ * concurrency would exhaust the host. This module runs at most three analyses
+ * at a time and returns summaries, not full reports.
+ *
+ * @module dshm-compat/batch
+ */
+import { analyze } from './analyze.js'
+
+const DEFAULT_CONCURRENCY = 3
+const MAX_SPECS = 50
+
+/**
+ * @param {string[]} specs
+ * @param {{ concurrency?: number, textScan?: boolean, signal?: AbortSignal, registry?: string }} [options]
+ */
+export async function scan(specs, options = {}) {
+  if (!Array.isArray(specs)) throw Object.assign(new Error('specs must be an array'), { code: 'INVALID_SPEC' })
+  const unique = [...new Set(specs.filter(spec => typeof spec === 'string' && spec.trim() !== '').map(spec => spec.trim()))]
+  if (unique.length > MAX_SPECS) throw Object.assign(new Error(`at most ${MAX_SPECS} specs per scan`), { code: 'TOO_MANY_SPECS' })
+  const concurrency = Math.max(1, Math.min(options.concurrency ?? DEFAULT_CONCURRENCY, 5, unique.length || 1))
+  /** @type {Array<{ spec: string, ok: boolean, strategy?: string, confidence?: string, name?: string, version?: string, error?: string, fingerprint?: string }>} */
+  const items = new Array(unique.length)
+  let next = 0
+  const worker = async () => {
+    for (;;) {
+      const index = next
+      next += 1
+      if (index >= unique.length) return
+      const spec = unique[index]
+      try {
+        const report = await analyze(spec, { textScan: options.textScan === true, signal: options.signal, registry: options.registry })
+        items[index] = {
+          spec,
+          ok: true,
+          strategy: report.strategy,
+          confidence: report.confidence,
+          name: report.resolved?.name,
+          version: report.resolved?.version,
+          fingerprint: report.fingerprint,
+          report,
+        }
+      } catch (error) {
+        items[index] = { spec, ok: false, error: String(error?.message ?? error) }
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: concurrency }, worker))
+
+  const counts = { total: unique.length, ok: 0, error: 0, S0: 0, S1: 0, S2: 0, S3: 0, S4: 0 }
+  for (const item of items) {
+    if (!item.ok) { counts.error += 1; continue }
+    counts.ok += 1
+    counts[item.strategy] += 1
+  }
+  return { counts, items }
+}