@lievclouds/dsh-cortex 0.5.4 → 1.0.0

package/src/host/miniapp/roots.js

@@ -0,0 +1,360 @@
+/**
+ * Mini-program (wxapkg) root discovery and identity inference.
+ *
+ * All functions are pure path math over the environment (plus `existsSync`
+ * checks in `expandRoots`) so they are trivially testable with fake envs and
+ * temp trees. Nothing here writes to disk or touches WeChat's cache.
+ *
+ * Layouts handled:
+ *   WeChat 4.x (xwechat)  <appdata>/Tencent/xwechat/radium/users/<hash>/applet/packages/<appid>/<version>/*.wxapkg
+ *   public library        <users>/<hash>/applet/publicLib/<version>/publicLib.wxapkg
+ *   WeChat 3.x            <home>/Documents/WeChat Files/.../packages/<appid>/<version>/*.wxapkg
+ *   devtools              <localappdata>/微信web开发者工具/User Data/...
+ *   custom/env roots      arbitrary depth (`CORTEX_MINIAPP_ROOTS`)
+ */
+
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, delimiter, dirname, join, relative, resolve, sep } from 'node:path'
+
+/** @typedef {{kind:'xwechat'|'wechat3'|'devtools'|'custom', path:string, label:string, mode:'packages'|'recursive', maxDepth:number}} Root */
+
+/** Default recursive scan depth used by discovery and detection. */
+export const DEFAULT_MAX_DEPTH = 10
+
+/** Appid directory segment, e.g. `wxdabf06925a55f410`. */
+const APPID_RE = /^wx[0-9a-f]{16}$/i
+
+/** Directory names that are never descended into. */
+const SKIP_DIR_NAMES = new Set(['node_modules'])
+
+/** @param {NodeJS.ProcessEnv} env */
+function homeDir(env) {
+  if (env && typeof env.HOME === 'string' && env.HOME.trim()) return env.HOME.trim()
+  if (env && typeof env.USERPROFILE === 'string' && env.USERPROFILE.trim()) return env.USERPROFILE.trim()
+  return homedir()
+}
+
+/** @param {NodeJS.ProcessEnv} env */
+function appDataDir(env) {
+  if (env && typeof env.APPDATA === 'string' && env.APPDATA.trim()) return env.APPDATA.trim()
+  return join(homeDir(env), 'AppData', 'Roaming')
+}
+
+/** @param {NodeJS.ProcessEnv} env */
+function localAppDataDir(env) {
+  if (env && typeof env.LOCALAPPDATA === 'string' && env.LOCALAPPDATA.trim()) return env.LOCALAPPDATA.trim()
+  return join(homeDir(env), 'AppData', 'Local')
+}
+
+/**
+ * Candidate roots (existing or not; `expandRoots` applies the existence filter).
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {Root[]}
+ */
+export function defaultRoots(env = process.env) {
+  const roots = [
+    {
+      kind: 'xwechat',
+      path: resolve(join(appDataDir(env), 'Tencent', 'xwechat', 'radium', 'users')),
+      label: 'WeChat 4.x (xwechat)',
+      mode: 'recursive',
+      maxDepth: DEFAULT_MAX_DEPTH,
+    },
+    {
+      kind: 'wechat3',
+      path: resolve(join(homeDir(env), 'Documents', 'WeChat Files')),
+      label: 'WeChat Files (3.x)',
+      mode: 'recursive',
+      maxDepth: DEFAULT_MAX_DEPTH,
+    },
+    {
+      kind: 'devtools',
+      path: resolve(join(localAppDataDir(env), '微信web开发者工具', 'User Data')),
+      label: 'WeChat DevTools',
+      mode: 'recursive',
+      maxDepth: DEFAULT_MAX_DEPTH,
+    },
+  ]
+
+  // WeChat 4.x can keep its "files" directory on another drive (or the user's
+  // Documents folder). Its account data may still contain applet caches; scan
+  // every discovered `Documents` directory without touching the whole drive.
+  const documents = new Set([resolve(join(homeDir(env), 'Documents'))])
+  // Extra-drive probing is opt-in (host sets the flag at runtime) so tests and
+  // embedders with a synthetic env never touch unrelated drives.
+  if (env && env.CORTEX_MINIAPP_EXTRA_DRIVES === '1') {
+    for (const letter of 'CDEFGHIJKLMNOPQRSTUVWXYZ') {
+      const driveDocuments = `${letter}:\\Documents`
+      try {
+        if (existsSync(driveDocuments)) documents.add(driveDocuments)
+      } catch {
+        /* inaccessible drive letter */
+      }
+    }
+  }
+  for (const directory of documents) {
+    const xwechatFiles = join(directory, 'xwechat_files')
+    try {
+      if (existsSync(xwechatFiles)) {
+        roots.push({
+          kind: 'xwechat',
+          path: resolve(xwechatFiles),
+          label: `WeChat 4.x files (${directory.slice(0, 2)})`,
+          mode: 'recursive',
+          maxDepth: DEFAULT_MAX_DEPTH,
+        })
+      }
+    } catch {
+      /* ignore */
+    }
+    const classic = join(directory, 'WeChat Files')
+    try {
+      if (existsSync(classic)) {
+        roots.push({
+          kind: 'wechat3',
+          path: resolve(classic),
+          label: `WeChat Files (${directory.slice(0, 2)})`,
+          mode: 'recursive',
+          maxDepth: DEFAULT_MAX_DEPTH,
+        })
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  return roots
+}
+
+/**
+ * Extra roots from `CORTEX_MINIAPP_ROOTS` (split on `path.delimiter`).
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string[]} absolute paths
+ */
+export function envRoots(env = process.env) {
+  const raw = env && typeof env.CORTEX_MINIAPP_ROOTS === 'string' ? env.CORTEX_MINIAPP_ROOTS : ''
+  if (!raw.trim()) return []
+  const out = []
+  for (const part of raw.split(delimiter)) {
+    let value = part.trim()
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1).trim()
+    if (!value) continue
+    out.push(resolve(value))
+  }
+  return out
+}
+
+/** @param {string} value */
+function rootKey(value) {
+  const absolute = resolve(value)
+  return process.platform === 'win32' ? absolute.toLowerCase() : absolute
+}
+
+/**
+ * Resolve the effective root list: existing defaults first, then custom and
+ * env roots. Non-existent roots are dropped unless `includeMissing`.
+ * @param {{customRoots?:string[], env?:NodeJS.ProcessEnv, includeMissing?:boolean}} [options]
+ * @returns {Root[]}
+ */
+export function expandRoots({ customRoots = [], env = process.env, includeMissing = false } = {}) {
+  /** @type {Root[]} */
+  const roots = []
+  const seen = new Set()
+  const push = (root) => {
+    const key = rootKey(root.path)
+    if (seen.has(key)) return
+    seen.add(key)
+    roots.push(root)
+  }
+
+  for (const root of defaultRoots(env)) {
+    const exists = existsSync(root.path)
+    if (exists || includeMissing) push({ ...root, path: resolve(root.path) })
+  }
+
+  const extra = []
+  for (const entry of Array.isArray(customRoots) ? customRoots : []) {
+    if (typeof entry === 'string' && entry.trim()) extra.push(entry.trim())
+  }
+  extra.push(...envRoots(env))
+
+  for (const entry of extra) {
+    const absolute = resolve(entry)
+    const exists = existsSync(absolute)
+    if (!exists && !includeMissing) continue
+    push({
+      kind: 'custom',
+      path: absolute,
+      label: basename(absolute) || absolute,
+      mode: 'recursive',
+      maxDepth: DEFAULT_MAX_DEPTH,
+    })
+  }
+
+  return roots
+}
+
+/**
+ * Sanitize one path segment for use below the miniapp workspace.
+ * @param {string} value
+ * @param {string} [fallback]
+ * @returns {string}
+ */
+export function sanitizeSegment(value, fallback = '_') {
+  const raw = typeof value === 'string' ? value : value === undefined || value === null ? '' : String(value)
+  let out = raw
+    .replace(/[\u0000-\u001f<>:"/\\|?*]/g, '_')
+    .replace(/^[.\s]+/, '')
+    .replace(/[.\s]+$/, '')
+  if (!out) return fallback
+  if (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i.test(out)) out = `_${out}`
+  return out.slice(0, 120)
+}
+
+/** @param {string} value */
+function isInsideRoot(rootPath, target) {
+  const root = resolve(rootPath)
+  const path = resolve(target)
+  if (process.platform === 'win32') {
+    const lowerRoot = root.toLowerCase()
+    const lowerPath = path.toLowerCase()
+    return lowerPath === lowerRoot || lowerPath.startsWith(lowerRoot + sep)
+  }
+  return path === root || path.startsWith(root + sep)
+}
+
+/** @param {string} segment */
+function isVersionSegment(segment) {
+  if (!segment || segment.length > 32) return false
+  if (/^\d+$/.test(segment)) return true
+  if (/^\d+(?:\.\d+){1,3}$/.test(segment)) return true
+  if (/^\d{4}[-_.]\d{2}[-_.]\d{2}(?:[T _.-].*)?$/.test(segment)) return true
+  return false
+}
+
+/**
+ * Strip `_packages_` prefixes and app bookkeeping names, then accept only a
+ * canonical wx appid segment.
+ * @param {string} segment
+ * @returns {string}
+ */
+function appidFromSegment(segment) {
+  let value = String(segment ?? '').trim()
+  if (!value || SKIP_DIR_NAMES.has(value.toLowerCase())) return ''
+  const lower = value.toLowerCase()
+  const marker = lower.indexOf('_packages_')
+  if (marker >= 0) value = value.slice(marker + '_packages_'.length)
+  if (/^_?(?:__app__|publiclib)$/i.test(value)) return ''
+  if (APPID_RE.test(value)) return value
+  return ''
+}
+
+/**
+ * Derive `{appid, version, packageDir, packageName, rootPath, rootKind}` from
+ * one package file and the scan root that produced it.
+ *
+ * @param {string} filePath
+ * @param {Root|{kind?:string, path:string}|string} root
+ */
+export function inferIdentity(filePath, root) {
+  const rootPath = resolve(typeof root === 'string' ? root : root && root.path ? root.path : process.cwd())
+  const rootKind = typeof root === 'object' && root && typeof root.kind === 'string' && root.kind ? root.kind : 'custom'
+  const fileAbs = resolve(filePath)
+  const inside = isInsideRoot(rootPath, fileAbs)
+  const packageDir = inside ? dirname(fileAbs) : rootPath
+
+  const base = basename(fileAbs)
+  const packageName = base.toLowerCase().endsWith('.wxapkg') ? base.slice(0, -'.wxapkg'.length) : base
+
+  /** @type {string} */
+  let appid = ''
+  /** @type {string} */
+  let version = ''
+
+  if (inside) {
+    const segments = relative(rootPath, packageDir)
+      .split(/[\\/]+/)
+      .filter(Boolean)
+
+    // 1. publicLib layout: .../applet/publicLib/<version>/publicLib.wxapkg
+    let publicLibIndex = -1
+    for (let index = segments.length - 1; index >= 0; index -= 1) {
+      if (segments[index].toLowerCase() === 'publiclib') {
+        publicLibIndex = index
+        break
+      }
+    }
+    if (publicLibIndex >= 0) {
+      const candidate = segments[publicLibIndex + 1] || ''
+      return {
+        appid: 'publicLib',
+        version: isVersionSegment(candidate) ? candidate : '',
+        packageDir,
+        packageName,
+        rootPath,
+        rootKind,
+      }
+    }
+
+    // 2. canonical wx appid directory, nearest the file first.
+    let appidIndex = -1
+    for (let index = segments.length - 1; index >= 0; index -= 1) {
+      const candidate = appidFromSegment(segments[index])
+      if (candidate) {
+        appid = candidate
+        appidIndex = index
+        break
+      }
+    }
+
+    if (appidIndex >= 0) {
+      for (let index = appidIndex + 1; index < segments.length; index += 1) {
+        if (isVersionSegment(segments[index])) {
+          version = segments[index]
+          break
+        }
+      }
+    }
+  }
+
+  return { appid, version, packageDir, packageName, rootPath, rootKind }
+}
+
+/**
+ * Absolute miniapp workspace root (`CORTEX_MINIAPP_WORKSPACE` or
+ * `~/.cortex/miniapps`).
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function miniAppWorkspaceRoot(env = process.env) {
+  const override =
+    env && typeof env.CORTEX_MINIAPP_WORKSPACE === 'string' ? env.CORTEX_MINIAPP_WORKSPACE.trim() : ''
+  return resolve(override || join(homeDir(env), '.cortex', 'miniapps'))
+}
+
+/**
+ * Per-package workspace layout:
+ *   <root>/<appid>/<version>/
+ *     unpacked/            extracted app files + manifest.json + overview.json
+ *
+ * `manifestPath` / `extractedPath` live inside `unpacked` so the unpack and
+ * analyze helpers can address them from `unpacked_path` alone.
+ *
+ * @param {string} appid
+ * @param {string} version
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function packageWorkspace(appid, version, env = process.env) {
+  const root = join(
+    miniAppWorkspaceRoot(env),
+    sanitizeSegment(appid, 'unknown'),
+    sanitizeSegment(version, 'unknown'),
+  )
+  const unpacked = join(root, 'unpacked')
+  return {
+    root,
+    unpacked,
+    manifestPath: join(unpacked, 'manifest.json'),
+    extractedPath: join(unpacked, 'extracted.json'),
+  }
+}

package/src/host/miniapp/routes.js

@@ -0,0 +1,304 @@
+/**
+ * HTTP surface for the mini-program (wxapkg) reverse-engineering feature.
+ *
+ * Mounted under `/cortex-api/cortex/miniapps/**`. The parent dispatcher
+ * (`src/host/cortex/index.js`) already applied the loopback peer/Host fences and
+ * the same-origin write fence, so this module only routes, validates input and
+ * maps the shared service layer onto JSON responses.
+ *
+ * The parent imports this file lazily: a failure in the miniapp modules must
+ * never take down the rest of the Cortex UI/API.
+ */
+
+import { existsSync } from 'node:fs'
+import { isAbsolute, resolve } from 'node:path'
+import {
+  badRequest,
+  methodNotAllowed,
+  queryBool01,
+  queryInt,
+  queryString,
+  readJsonBody,
+  safeDecode,
+  sendJson,
+} from '../http.js'
+import { defaultRoots, expandRoots } from './roots.js'
+import {
+  analyzeSourceRecord,
+  detailPayload,
+  fileForSource,
+  importAssetsForSource,
+  listMiniapps,
+  miniappStore,
+  openSourceDirectory,
+  requireSourceById,
+  scan,
+  searchSource,
+  treeForSource,
+  unpackSourceRecord,
+} from './service.js'
+
+const MAX_ID = 200
+const MAX_PATH = 4000
+const MAX_CUSTOM_ROOTS = 20
+
+function sourceId(ctx) {
+  const raw = Array.isArray(ctx.params) ? ctx.params[0] : ''
+  const id = safeDecode(raw, 'miniapp id')
+  if (id.length === 0) throw badRequest('miniapp id is required')
+  if (id.length > MAX_ID) throw badRequest('miniapp id is too long', { max: MAX_ID })
+  return id
+}
+
+/** Read a JSON body when present; empty POSTs are treated as `{}`. */
+async function bodyOrEmpty(req) {
+  const headers = (req && req.headers) || {}
+  const length = Number(headers['content-length'] || 0)
+  if (length === 0 && headers['transfer-encoding'] === undefined) return {}
+  return readJsonBody(req)
+}
+
+export async function handleList({ res, searchParams }) {
+  const search = queryString(searchParams, 'search', { max: 400 }) ?? ''
+  const status = queryString(searchParams, 'status', { max: 40 }) ?? ''
+  sendJson(res, 200, listMiniapps(miniappStore(), { search, status }))
+}
+
+export async function handleScan({ req, res }) {
+  const body = await bodyOrEmpty(req)
+  let customRoots
+  // An empty array from the UI means "scan with the saved roots"; only a
+  // non-empty array replaces them. Clearing is done through POST /miniapps/roots.
+  if (Array.isArray(body.customRoots) && body.customRoots.length > 0) {
+    customRoots = normalizeRoots(body.customRoots)
+  }
+  const result = await scan(miniappStore(), { customRoots })
+  sendJson(res, 200, result)
+}
+
+function rootsPayload(customRoots) {
+  const all = expandRoots({ customRoots, includeMissing: true }).map((root) => ({
+    kind: root.kind,
+    path: root.path,
+    label: root.label,
+    mode: root.mode,
+    exists: existsSync(root.path),
+  }))
+  return { roots: all, customRoots }
+}
+
+export function handleRootsGet({ res }) {
+  const store = miniappStore()
+  sendJson(res, 200, rootsPayload(store.customRoots()))
+}
+
+export async function handleRootsSet({ req, res }) {
+  const body = await readJsonBody(req)
+  const roots = normalizeRoots(body.roots)
+  const mode = body.mode === 'append' ? 'append' : 'replace'
+  const store = miniappStore()
+  const next = mode === 'append' ? [...new Set([...store.customRoots(), ...roots])] : roots
+  store.setCustomRoots(next)
+  sendJson(res, 200, rootsPayload(next))
+}
+
+export async function handleDetailRoute(ctx) {
+  const store = miniappStore()
+  const source = requireSourceById(store, sourceId(ctx))
+  sendJson(ctx.res, 200, detailPayload(store, source))
+}
+
+export async function handleUnpack(ctx) {
+  const store = miniappStore()
+  const source = requireSourceById(store, sourceId(ctx))
+  let force = false
+  try {
+    const body = await bodyOrEmpty(ctx.req)
+    force = body.force === true
+  } catch {
+    force = false
+  }
+  const result = await unpackSourceRecord({ store, source, force })
+  const row = store.getSource(source.id) || source
+  sendJson(ctx.res, 200, {
+    ok: result.ok === true,
+    status: result.status,
+    cached: result.cached === true,
+    error: result.error || '',
+    totals: result.totals || null,
+    unpackedPath: result.unpackedPath || '',
+    manifest: result.manifest || null,
+    miniapp: detailPayload(store, row).miniapp,
+  })
+}
+
+export async function handleAnalyze(ctx) {
+  const store = miniappStore()
+  const source = requireSourceById(store, sourceId(ctx))
+  let force = false
+  try {
+    const body = await bodyOrEmpty(ctx.req)
+    force = body.force === true
+  } catch {
+    force = false
+  }
+  const result = analyzeSourceRecord({ store, source, force })
+  const row = store.getSource(source.id) || source
+  sendJson(ctx.res, 200, {
+    ok: result.ok,
+    cached: result.cached === true,
+    analysis: result.analysis,
+    overviewText: result.overviewText,
+    counts: result.counts,
+    miniapp: detailPayload(store, row).miniapp,
+  })
+}
+
+export function handleTreeRoute(ctx) {
+  const source = requireSourceById(miniappStore(), sourceId(ctx))
+  const path = queryString(ctx.searchParams, 'path', { max: MAX_PATH }) ?? ''
+  sendJson(ctx.res, 200, treeForSource(source, path))
+}
+
+export function handleFileRoute(ctx) {
+  const source = requireSourceById(miniappStore(), sourceId(ctx))
+  const path = queryString(ctx.searchParams, 'path', { max: MAX_PATH })
+  if (!path) throw badRequest('path is required', { field: 'path' })
+  const offset = queryInt(ctx.searchParams, 'offset', { min: 0, max: 10_000_000 }) ?? 0
+  const limit = queryInt(ctx.searchParams, 'limit', { min: 1, max: 5000 }) ?? 200
+  const maxBytes = queryInt(ctx.searchParams, 'maxBytes', { min: 1024, max: 5 * 1024 * 1024 }) ?? 1024 * 1024
+  const rawFormat = queryBool01(ctx.searchParams, 'format')
+  const find = queryString(ctx.searchParams, 'find', { max: 400 }) ?? ''
+  const findRegex = queryBool01(ctx.searchParams, 'findRegex') === true
+  const findMax = queryInt(ctx.searchParams, 'findMax', { min: 1, max: 1000 }) ?? 200
+  const result = fileForSource(source, path, {
+    offset,
+    limit,
+    format: rawFormat === false ? false : 'auto',
+    maxBytes,
+    find,
+    findRegex,
+    findMax,
+  })
+  if (result.binary) {
+    throw badRequest('binary files cannot be previewed as text', {
+      code: 'BINARY_FILE',
+      path: result.path,
+      size: result.size,
+    })
+  }
+  sendJson(ctx.res, 200, result)
+}
+
+export function handleSearchRoute(ctx) {
+  const source = requireSourceById(miniappStore(), sourceId(ctx))
+  const query = queryString(ctx.searchParams, 'query', { max: 400 })
+  if (!query) throw badRequest('query is required', { field: 'query' })
+  const regex = queryBool01(ctx.searchParams, 'regex') === true
+  const glob = queryString(ctx.searchParams, 'glob', { max: 300 }) ?? ''
+  const maxResults = queryInt(ctx.searchParams, 'maxResults', { min: 1, max: 200 }) ?? 50
+  sendJson(ctx.res, 200, searchSource(source, { query, regex, glob, maxResults }))
+}
+
+export async function handleImportAssets(ctx) {
+  const store = miniappStore()
+  const source = requireSourceById(store, sourceId(ctx))
+  const body = await bodyOrEmpty(ctx.req)
+  const projectName =
+    typeof body.project_name === 'string' && body.project_name.trim().length > 0
+      ? body.project_name.trim().slice(0, 120)
+      : undefined
+  const hostPort =
+    typeof body.host_port === 'string' && body.host_port.trim().length > 0
+      ? body.host_port.trim().slice(0, 4000)
+      : undefined
+  const result = await importAssetsForSource({
+    holder: ctx.holder,
+    store,
+    source,
+    projectName,
+    hostPort,
+  })
+  sendJson(ctx.res, 200, result)
+}
+
+export async function handleOpen(ctx) {
+  const store = miniappStore()
+  const source = requireSourceById(store, sourceId(ctx))
+  sendJson(ctx.res, 200, openSourceDirectory(source))
+}
+
+export async function handleRename(ctx) {
+  const store = miniappStore()
+  const source = requireSourceById(store, sourceId(ctx))
+  const body = await bodyOrEmpty(ctx.req)
+  const raw = typeof body.app_name === 'string' ? body.app_name : ''
+  if (raw.length > 120) throw badRequest('app_name is too long', { field: 'app_name', max: 120 })
+  const appName = raw.replace(/\s+/g, ' ').trim().slice(0, 60)
+  const row = store.updateSource(source.id, { app_name: appName })
+  sendJson(ctx.res, 200, { ok: true, miniapp: detailPayload(store, row || source).miniapp })
+}
+
+function normalizeRoots(raw) {
+  if (!Array.isArray(raw)) throw badRequest('roots must be an array', { field: 'roots' })
+  if (raw.length > MAX_CUSTOM_ROOTS) throw badRequest(`at most ${MAX_CUSTOM_ROOTS} custom roots`, { max: MAX_CUSTOM_ROOTS })
+  const result = []
+  for (const value of raw) {
+    if (typeof value !== 'string') throw badRequest('each root must be a string', { field: 'roots' })
+    const trimmed = value.trim()
+    if (trimmed.length === 0) continue
+    if (trimmed.length > 2000) throw badRequest('root path is too long', { field: 'roots', max: 2000 })
+    if (!isAbsolute(trimmed)) throw badRequest('root path must be absolute', { field: 'roots' })
+    const resolved = resolve(trimmed)
+    if (!result.includes(resolved)) result.push(resolved)
+  }
+  return result
+}
+
+/* -------------------------------- routing -------------------------------- */
+
+const ROUTES = [
+  { method: 'GET', pattern: /^\/miniapps$/, handler: handleList },
+  { method: 'POST', pattern: /^\/miniapps\/scan$/, handler: handleScan },
+  { method: 'GET', pattern: /^\/miniapps\/roots$/, handler: handleRootsGet },
+  { method: 'POST', pattern: /^\/miniapps\/roots$/, handler: handleRootsSet },
+  { method: 'POST', pattern: /^\/miniapps\/([^/]+)\/unpack$/, handler: handleUnpack },
+  { method: 'POST', pattern: /^\/miniapps\/([^/]+)\/analyze$/, handler: handleAnalyze },
+  { method: 'POST', pattern: /^\/miniapps\/([^/]+)\/import-assets$/, handler: handleImportAssets },
+  { method: 'POST', pattern: /^\/miniapps\/([^/]+)\/open$/, handler: handleOpen },
+  { method: 'POST', pattern: /^\/miniapps\/([^/]+)\/name$/, handler: handleRename },
+  { method: 'GET', pattern: /^\/miniapps\/([^/]+)\/tree$/, handler: handleTreeRoute },
+  { method: 'GET', pattern: /^\/miniapps\/([^/]+)\/file$/, handler: handleFileRoute },
+  { method: 'GET', pattern: /^\/miniapps\/([^/]+)\/search$/, handler: handleSearchRoute },
+  { method: 'GET', pattern: /^\/miniapps\/([^/]+)$/, handler: handleDetailRoute },
+]
+
+/**
+ * Handle one `/miniapps/**` request. Returns false when the path is not ours
+ * (the parent dispatcher then falls through to its own route table).
+ * @param {Record<string, any>} ctx
+ */
+export async function handleMiniapps(ctx) {
+  const path = String(ctx.path || '')
+  const method = String(ctx.method || 'GET').toUpperCase()
+  if (path !== '/miniapps' && !path.startsWith('/miniapps/')) return false
+  const matched = ROUTES.filter((route) => route.pattern.test(path))
+  if (matched.length === 0) return false
+  const route = matched.find((candidate) => candidate.method === method)
+  if (!route) throw methodNotAllowed()
+  const match = route.pattern.exec(path)
+  ctx.params = match.slice(1)
+  try {
+    await route.handler(ctx)
+  } catch (error) {
+    // Workspace/container errors are client-visible 4xx, never opaque 500s.
+    if (error && error.name === 'WxapkgError') {
+      throw badRequest(error.message || 'mini-program operation failed', { code: error.code })
+    }
+    throw error
+  }
+  return true
+}
+
+/** Exposed for diagnostics/tests (not part of the public HTTP contract). */
+export { ROUTES as MINIAPP_ROUTES, defaultRoots }