@lf_maple/koishi-plugin-phi-plugin-full 0.1.80

package/core/model/theme/catalog.js

@@ -0,0 +1,192 @@
+import { resolveBotDownloadAllowed, ThemeMarketClientError } from './marketClient.js'
+import makeRequest from '../api/makeRequest.js'
+import themeManager from './manager.js'
+
+export const THEME_MARKET_API_ORIGIN = 'https://lyh.org.cn:18473'
+const SLUG_RE = /^[a-z][a-z0-9_-]{0,119}$/
+const PINNED_LOCAL_THEME_ID = 'milthm'
+const MAX_MARKET_THEMES = 500
+export const THEME_MARKET_PAGE_SIZE = 6
+
+/** @param {unknown} value */
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function invalidCatalogResponse() {
+    return new ThemeMarketClientError('theme_store_invalid_response', 502)
+}
+
+/** @param {unknown} value @param {number} limit */
+function text(value, limit) {
+    return typeof value === 'string' ? value.trim().slice(0, limit) : ''
+}
+
+/** @param {unknown} value */
+function safeCover(value) {
+    if (!value) return ''
+    try {
+        const url = new URL(String(value))
+        return url.protocol === 'https:' && url.origin === THEME_MARKET_API_ORIGIN ? url.toString() : ''
+    } catch {
+        return ''
+    }
+}
+
+/**
+ * @param {any} item
+ * @param {boolean|null} [inheritedBotDownloadAllowed]
+ */
+export function normalizeMarketTheme(item, inheritedBotDownloadAllowed = null) {
+    const slug = text(item?.slug || item?.themeId, 120).toLowerCase()
+    const botDownloadAllowed = typeof item?.botDownloadAllowed === 'boolean'
+        ? item.botDownloadAllowed
+        : inheritedBotDownloadAllowed
+    return {
+        slug,
+        themeId: text(item?.themeId || slug, 120),
+        name: text(item?.name || slug, 100) || slug,
+        author: text(item?.author, 80),
+        summary: text(item?.summary, 180),
+        description: text(item?.description, 1200),
+        cover: safeCover(item?.cover),
+        tags: Array.isArray(item?.tags) ? item.tags.filter((/** @type {unknown} */ tag) => typeof tag === 'string').slice(0, 8).map((/** @type {string} */ tag) => tag.slice(0, 24)) : [],
+        version: text(item?.version, 64),
+        downloadPolicy: ['public', 'restricted', 'bot_only'].includes(item?.downloadPolicy) ? item.downloadPolicy : 'restricted',
+        compatibility: text(item?.compatibility, 100),
+        downloads: Number.isSafeInteger(item?.downloads) && item.downloads >= 0 ? item.downloads : 0,
+        updatedAt: text(item?.updatedAt, 40),
+        featured: item?.featured === true,
+        size: Number.isSafeInteger(item?.size) && item.size > 0 ? item.size : 0,
+        botDownloadAllowed,
+        local: false,
+        pinnedLocal: false,
+    }
+}
+
+/** @param {any[]} themes @param {string} query @param {number} page @param {boolean} localOnly */
+function paginateThemes(themes, query, page, localOnly) {
+    const needle = text(query, 80).toLocaleLowerCase()
+    const filtered = needle
+        ? themes.filter((/** @type {any} */ theme) => [theme.slug, theme.name, theme.author, theme.summary, theme.description, ...theme.tags]
+            .some((/** @type {string} */ value) => value.toLocaleLowerCase().includes(needle)))
+        : themes
+    if (!localOnly) {
+        filtered.sort((/** @type {any} */ a, /** @type {any} */ b) => Number(b.pinnedLocal) - Number(a.pinnedLocal)
+            || Number(b.featured) - Number(a.featured)
+            || b.updatedAt.localeCompare(a.updatedAt))
+    }
+    const total = filtered.length
+    const pageCount = Math.max(1, Math.ceil(total / THEME_MARKET_PAGE_SIZE))
+    const currentPage = Number.isSafeInteger(page) ? Math.min(Math.max(page, 1), pageCount) : 1
+    const start = (currentPage - 1) * THEME_MARKET_PAGE_SIZE
+    return {
+        themes: filtered.slice(start, start + THEME_MARKET_PAGE_SIZE),
+        query: needle,
+        page: currentPage,
+        pageCount,
+        total,
+        localOnly,
+    }
+}
+
+/** @param {any} theme */
+function normalizeLocalTheme(theme) {
+    return {
+        slug: theme.id,
+        themeId: theme.id,
+        name: theme.name || theme.id,
+        author: theme.author || '',
+        summary: theme.description || '',
+        description: theme.description || '',
+        cover: '',
+        tags: [theme.marketInstalled ? '已下载' : '本地主题'],
+        version: theme.marketVersion || '',
+        downloadPolicy: 'local',
+        compatibility: '本地已安装',
+        downloads: 0,
+        updatedAt: '',
+        featured: false,
+        size: 0,
+        botDownloadAllowed: themeManager.isThemeAvailable(theme.id),
+        local: true,
+        pinnedLocal: theme.id === PINNED_LOCAL_THEME_ID,
+    }
+}
+
+/**
+ * 返回当前进程已注册的本地自定义主题目录，不访问网络。
+ * @param {string} [query]
+ * @param {number} [page]
+ */
+export function getLocalThemeCatalog(query = '', page = 1) {
+    const themes = themeManager.getCustomThemes().map(normalizeLocalTheme)
+    return { demo: false, ...paginateThemes(themes, query, page, true) }
+}
+
+/** @param {string} themeId */
+export function getLocalThemeDetail(themeId) {
+    const theme = themeManager.getTheme(themeId)
+    if (!theme || !themeManager.isCustomTheme(themeId)) return null
+    return { ...normalizeLocalTheme(theme), releaseNotes: '' }
+}
+
+/** @param {any} response @param {any} item */
+function validateCatalogTheme(response, item) {
+    if (!isRecord(item)
+        || typeof item.slug !== 'string' || !SLUG_RE.test(item.slug)
+        || typeof item.name !== 'string' || !item.name.trim() || item.name.length > 100
+        || Object.hasOwn(item, 'downloadPolicy') && !['public', 'restricted', 'bot_only'].includes(item.downloadPolicy)
+        || Object.hasOwn(item, 'tags') && (!Array.isArray(item.tags) || item.tags.some((/** @type {unknown} */ tag) => typeof tag !== 'string'))) {
+        throw invalidCatalogResponse()
+    }
+    const botDownloadAllowed = resolveBotDownloadAllowed(response, item)
+    return normalizeMarketTheme(item, botDownloadAllowed)
+}
+
+/**
+ * @param {string} [query]
+ * @param {number} [page]
+ */
+export async function fetchThemeCatalog(query = '', page = 1) {
+    const data = /** @type {any} */ (await makeRequest.getThemeMarketList())
+    if (!isRecord(data)
+        || data.ok !== true
+        || !Array.isArray(data.themes)
+        || data.themes.length > MAX_MARKET_THEMES
+        || Object.hasOwn(data, 'demo') && typeof data.demo !== 'boolean') {
+        throw invalidCatalogResponse()
+    }
+    const seen = new Set()
+    const onlineThemes = []
+    for (const item of data.themes) {
+        const theme = validateCatalogTheme(data, item)
+        if (seen.has(theme.slug)) continue
+        seen.add(theme.slug)
+        onlineThemes.push(theme)
+    }
+    const pinnedLocalTheme = getLocalThemeDetail(PINNED_LOCAL_THEME_ID)
+    const themes = pinnedLocalTheme
+        ? [pinnedLocalTheme, ...onlineThemes.filter((/** @type {{slug:string}} */ theme) => theme.slug !== PINNED_LOCAL_THEME_ID)]
+        : onlineThemes
+    return {
+        demo: data?.demo === true,
+        ...paginateThemes(themes, query, page, false),
+    }
+}
+
+/** @param {string} slug */
+export async function fetchThemeDetail(slug) {
+    if (!SLUG_RE.test(slug)) throw new ThemeMarketClientError('theme_slug_invalid', 400)
+    const data = /** @type {any} */ (await makeRequest.getThemeMarketDetail(slug))
+    if (!isRecord(data) || data.ok !== true || !isRecord(data.theme)) throw invalidCatalogResponse()
+    if (Object.hasOwn(data, 'releaseNotes') && typeof data.releaseNotes !== 'string'
+        || Object.hasOwn(data.theme, 'releaseNotes') && typeof data.theme.releaseNotes !== 'string') {
+        throw invalidCatalogResponse()
+    }
+    const theme = validateCatalogTheme(data, data.theme)
+    if (theme.slug !== slug) throw invalidCatalogResponse()
+    return { ...theme, releaseNotes: text(data?.releaseNotes || data?.theme?.releaseNotes, 3000) }
+}
+
+export const isThemeSlug = (/** @type {unknown} */ value) => typeof value === 'string' && SLUG_RE.test(value)

package/core/model/theme/installGuard.js

@@ -0,0 +1,275 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { ThemeMarketClientError } from './marketClient.js'
+import { themesDir } from './paths.js'
+import { getBackupThemeId, readMarketReceipt } from './recovery.js'
+
+export const MARKET_INSTALL_LIMITS = Object.freeze({
+    maxPending: 8,
+    maxInstalled: 32,
+    maxDiskBytes: 512 * 1024 * 1024,
+    freshInstallsPerUser: 3,
+    freshInstallWindowMs: 60 * 60_000,
+})
+
+/** @param {string} directory */
+async function directorySize(directory) {
+    let total = 0
+    const entries = await fs.promises.readdir(directory, { withFileTypes: true })
+    for (const entry of entries) {
+        const target = path.join(directory, entry.name)
+        if (entry.isDirectory()) total += await directorySize(target)
+        else total += (await fs.promises.lstat(target)).size
+    }
+    return total
+}
+
+/**
+ * @param {{root?:string}} [options]
+ * @returns {Promise<{count:number,totalBytes:number,byTheme:Map<string, number>}>}
+ */
+export async function getMarketThemeStorageUsage(options = {}) {
+    const root = options.root || themesDir
+    const entries = await fs.promises.readdir(root, { withFileTypes: true }).catch(error => {
+        if (/** @type {any} */ (error)?.code === 'ENOENT') return []
+        throw error
+    })
+    /** @type {Map<string, number>} */
+    const byTheme = new Map()
+    let totalBytes = 0
+    for (const entry of entries) {
+        if (!entry.isDirectory()) continue
+        const themeId = entry.name.startsWith('.') ? getBackupThemeId(entry.name) : entry.name
+        if (!themeId) continue
+        const directory = path.join(root, entry.name)
+        const stat = await fs.promises.lstat(directory)
+        if (!stat.isDirectory() || stat.isSymbolicLink()) continue
+        const marker = await fs.promises.lstat(path.join(directory, '.phi-market.json')).catch(() => null)
+        const receipt = await readMarketReceipt(path.join(directory, '.phi-market.json'))
+        if (receipt?.slug !== themeId && !marker?.isFile()) continue
+        const bytes = await directorySize(directory)
+        byTheme.set(themeId, (byTheme.get(themeId) || 0) + bytes)
+        totalBytes += bytes
+    }
+    return { count: byTheme.size, totalBytes, byTheme }
+}
+
+/**
+ * Reject a new theme before downloading when the current installation already
+ * exhausts a hard quota. The staged directory is checked again before commit.
+ * @param {string} themeId
+ * @param {{root?:string,maxInstalled?:number,maxDiskBytes?:number}} [options]
+ */
+export async function assertFreshMarketInstallCapacity(themeId, options = {}) {
+    const usage = await getMarketThemeStorageUsage(options)
+    if (usage.byTheme.has(themeId)) return { fresh: false, usage }
+    const maxInstalled = options.maxInstalled ?? MARKET_INSTALL_LIMITS.maxInstalled
+    const maxDiskBytes = options.maxDiskBytes ?? MARKET_INSTALL_LIMITS.maxDiskBytes
+    if (usage.count >= maxInstalled) throw new ThemeMarketClientError('theme_install_count_quota_exceeded')
+    if (usage.totalBytes >= maxDiskBytes) throw new ThemeMarketClientError('theme_install_disk_quota_exceeded')
+    return { fresh: true, usage }
+}
+
+/**
+ * Check the exact post-commit count and byte usage while the install lock is held.
+ * @param {string} themeId
+ * @param {string} stagedDirectory
+ * @param {{root?:string,maxInstalled?:number,maxDiskBytes?:number}} [options]
+ */
+export async function assertMarketInstallQuota(themeId, stagedDirectory, options = {}) {
+    const usage = await getMarketThemeStorageUsage(options)
+    const incomingBytes = await directorySize(stagedDirectory)
+    const existingBytes = usage.byTheme.get(themeId) || 0
+    const nextCount = usage.count + (usage.byTheme.has(themeId) ? 0 : 1)
+    const nextBytes = usage.totalBytes - existingBytes + incomingBytes
+    const maxInstalled = options.maxInstalled ?? MARKET_INSTALL_LIMITS.maxInstalled
+    const maxDiskBytes = options.maxDiskBytes ?? MARKET_INSTALL_LIMITS.maxDiskBytes
+    if (nextCount > maxInstalled) throw new ThemeMarketClientError('theme_install_count_quota_exceeded')
+    if (nextBytes > maxDiskBytes) throw new ThemeMarketClientError('theme_install_disk_quota_exceeded')
+    return { count: nextCount, totalBytes: nextBytes }
+}
+
+export class FreshInstallRateLimiter {
+    /** @param {{limit?:number,windowMs?:number,now?:()=>number}} [options] */
+    constructor(options = {}) {
+        this.limit = options.limit ?? MARKET_INSTALL_LIMITS.freshInstallsPerUser
+        this.windowMs = options.windowMs ?? MARKET_INSTALL_LIMITS.freshInstallWindowMs
+        this.now = options.now || Date.now
+        /** @type {Map<string, number[]>} */
+        this.records = new Map()
+    }
+
+    /** @param {string} requesterId */
+    consume(requesterId) {
+        requesterId ||= 'unknown'
+        const now = this.now()
+        const cutoff = now - this.windowMs
+        const recent = (this.records.get(requesterId) || []).filter(timestamp => timestamp > cutoff)
+        if (recent.length >= this.limit) throw new ThemeMarketClientError('theme_install_rate_limited', 429)
+        recent.push(now)
+        this.records.set(requesterId, recent)
+        return true
+    }
+
+    /** @param {string} [requesterId] */
+    clear(requesterId) {
+        if (requesterId) this.records.delete(requesterId)
+        else this.records.clear()
+    }
+}
+
+export class PersistentFreshInstallRateLimiter {
+    /** @param {{filePath?:string,limit?:number,windowMs?:number,now?:()=>number}} [options] */
+    constructor(options = {}) {
+        this.filePath = options.filePath || path.join(themesDir, '.phi-market-rate-limits.json')
+        this.limit = options.limit ?? MARKET_INSTALL_LIMITS.freshInstallsPerUser
+        this.windowMs = options.windowMs ?? MARKET_INSTALL_LIMITS.freshInstallWindowMs
+        this.now = options.now || Date.now
+    }
+
+    /** @returns {Promise<Record<string, number[]>>} */
+    async readRecords() {
+        let value
+        try {
+            value = JSON.parse(await fs.promises.readFile(this.filePath, 'utf8'))
+        } catch (error) {
+            if (/** @type {any} */ (error)?.code === 'ENOENT') return {}
+            throw new ThemeMarketClientError('theme_install_rate_state_invalid')
+        }
+        if (value?.version !== 1 || !value.records || typeof value.records !== 'object' || Array.isArray(value.records)) {
+            throw new ThemeMarketClientError('theme_install_rate_state_invalid')
+        }
+        const entries = Object.entries(value.records)
+        if (entries.length > 10_000) throw new ThemeMarketClientError('theme_install_rate_state_invalid')
+        /** @type {Record<string, number[]>} */
+        const records = {}
+        for (const [key, timestamps] of entries) {
+            if (!/^[a-f0-9]{64}$/.test(key) || !Array.isArray(timestamps)
+                || timestamps.length > 1_000 || timestamps.some(item => !Number.isFinite(item))) {
+                throw new ThemeMarketClientError('theme_install_rate_state_invalid')
+            }
+            records[key] = timestamps
+        }
+        return records
+    }
+
+    /** @param {Record<string, number[]>} records */
+    async writeRecords(records) {
+        await fs.promises.mkdir(path.dirname(this.filePath), { recursive: true, mode: 0o700 })
+        const temporary = `${this.filePath}.${process.pid}.${crypto.randomUUID()}.tmp`
+        try {
+            await fs.promises.writeFile(temporary, `${JSON.stringify({ version: 1, records })}\n`, {
+                encoding: 'utf8', mode: 0o600, flag: 'wx',
+            })
+            await fs.promises.rename(temporary, this.filePath)
+        } finally {
+            await fs.promises.rm(temporary, { force: true }).catch(() => {})
+        }
+    }
+
+    /**
+     * The caller must hold the global market install lock so read-modify-write is
+     * atomic across Bot workers.
+     * @param {string} requesterId
+     */
+    async consume(requesterId) {
+        const requesterKey = crypto.createHash('sha256').update(requesterId || 'unknown').digest('hex')
+        const now = this.now()
+        const cutoff = now - this.windowMs
+        const records = await this.readRecords()
+        for (const [key, timestamps] of Object.entries(records)) {
+            const recent = timestamps.filter(timestamp => timestamp > cutoff)
+            if (recent.length) records[key] = recent
+            else delete records[key]
+        }
+        const recent = records[requesterKey] || []
+        if (recent.length >= this.limit) throw new ThemeMarketClientError('theme_install_rate_limited', 429)
+        if (!records[requesterKey] && Object.keys(records).length >= 10_000) {
+            throw new ThemeMarketClientError('theme_install_rate_limited', 429)
+        }
+        recent.push(now)
+        records[requesterKey] = recent
+        await this.writeRecords(records)
+        return true
+    }
+
+    /** @param {string} [requesterId] */
+    async clear(requesterId) {
+        if (requesterId === undefined) {
+            await fs.promises.rm(this.filePath, { force: true })
+            return
+        }
+        const records = await this.readRecords()
+        const requesterKey = crypto.createHash('sha256').update(requesterId || 'unknown').digest('hex')
+        delete records[requesterKey]
+        if (Object.keys(records).length) await this.writeRecords(records)
+        else await fs.promises.rm(this.filePath, { force: true })
+    }
+}
+
+export class ThemeInstallCoordinator {
+    /** @param {{maxPending?:number,concurrency?:number}} [options] */
+    constructor(options = {}) {
+        this.maxPending = options.maxPending ?? MARKET_INSTALL_LIMITS.maxPending
+        this.concurrency = options.concurrency ?? 1
+        this.active = 0
+        /** @type {Array<{key:string,operation:()=>Promise<any>,promise:Promise<any>,resolve:(value:any)=>void,reject:(error:unknown)=>void}>} */
+        this.queue = []
+        /** @type {Map<string, Promise<any>>} */
+        this.flights = new Map()
+    }
+
+    /** @template T @param {string} key @param {()=>Promise<T>} operation @returns {Promise<T>} */
+    schedule(key, operation) {
+        const existing = this.flights.get(key)
+        if (existing) return existing
+        if (this.active >= this.concurrency && this.queue.length >= this.maxPending) {
+            return Promise.reject(new ThemeMarketClientError('theme_install_queue_full', 429))
+        }
+
+        /** @type {(value:T)=>void} */ let resolve = () => {}
+        /** @type {(error:unknown)=>void} */ let reject = () => {}
+        const promise = new Promise((resolvePromise, rejectPromise) => {
+            resolve = resolvePromise
+            reject = rejectPromise
+        })
+        const task = { key, operation, promise, resolve, reject }
+        this.flights.set(key, promise)
+        if (this.active < this.concurrency) this.start(task)
+        else this.queue.push(task)
+        return promise
+    }
+
+    /** @param {{key:string,operation:()=>Promise<any>,promise:Promise<any>,resolve:(value:any)=>void,reject:(error:unknown)=>void}} task */
+    start(task) {
+        this.active++
+        Promise.resolve()
+            .then(task.operation)
+            .then(value => {
+                if (this.flights.get(task.key) === task.promise) this.flights.delete(task.key)
+                this.active--
+                const next = this.queue.shift()
+                if (next) this.start(next)
+                task.resolve(value)
+            }, error => {
+                if (this.flights.get(task.key) === task.promise) this.flights.delete(task.key)
+                this.active--
+                const next = this.queue.shift()
+                if (next) this.start(next)
+                task.reject(error)
+            })
+    }
+}
+
+export const freshInstallRateLimiter = new PersistentFreshInstallRateLimiter()
+export const marketInstallCoordinator = new ThemeInstallCoordinator()
+
+/** @param {any} event */
+export function getThemeInstallRequesterId(event) {
+    const userId = event?.user_id ?? event?.userId
+    if (userId === undefined || userId === null || userId === '') return ''
+    const platform = event?.platform || event?.adapter || 'unknown'
+    const botId = event?.self_id ?? event?.bot_id ?? event?.bot?.self_id ?? ''
+    return `${platform}:${botId}:${userId}`
+}

package/core/model/theme/installLock.js

@@ -0,0 +1,174 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { ThemeMarketClientError } from './marketClient.js'
+import { migrateLegacyThemeDirectories, themesDir } from './paths.js'
+
+const LOCK_PATH = path.join(themesDir, '.phi-market-install.lock')
+const LOCK_REAP_PREFIX = `${LOCK_PATH}.reap-`
+const LOCK_WAIT_MS = 120_000
+const LOCK_STALE_MS = 5 * 60_000
+
+/** @type {Promise<void>} */
+let processQueue = Promise.resolve()
+const installLockContext = new AsyncLocalStorage()
+
+/** @param {number} ms */
+const wait = ms => new Promise(resolve => setTimeout(resolve, ms))
+
+/** @returns {string | null} 本进程的调度器启动标识（clock ticks）；非 Linux 或 /proc 不可用时返回 null */
+function currentProcessStartIdentity() {
+    try {
+        const stat = fs.readFileSync(`/proc/${process.pid}/stat`, 'utf8')
+        // comm 字段可能含空格和括号，字段从最后一个 ')' 之后数起：其后首列是第 3 列 state，
+        // 因此第 22 列 starttime 的下标为 19。重启后 starttime 归零，可顺带识别跨重启的残留锁。
+        return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19] || null
+    } catch {
+        return null
+    }
+}
+
+/**
+ * 核对锁记录的 pid 当前是否仍是当初那个进程：pid 被无关进程复用时启动标识不同，
+ * 崩溃持有者的锁才能被回收，而不是被永久判为存活。
+ * @param {number} pid @param {string | undefined} identity
+ * @returns {boolean | null} 无法判定（非 Linux / proc 不可读 / 旧锁未记录）时为 null
+ */
+function processIdentityMatches(pid, identity) {
+    if (!identity) return null
+    try {
+        const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8')
+        const current = stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19]
+        return current ? current === identity : null
+    } catch {
+        return null
+    }
+}
+
+/** @param {number} pid @param {string | undefined} identity */
+function processAlive(pid, identity) {
+    if (!Number.isSafeInteger(pid) || pid <= 0) return false
+    try {
+        process.kill(pid, 0)
+    } catch (error) {
+        if (/** @type {any} */ (error)?.code !== 'EPERM') return false
+    }
+    // 无法核对启动标识时保持保守的“存活”结论，避免误清他人的锁。
+    return processIdentityMatches(pid, identity) !== false
+}
+
+/** @returns {Promise<{stat:fs.Stats,owner:any,generation:string}|null>} */
+async function readFileLockState() {
+    const stat = await fs.promises.stat(LOCK_PATH).catch(() => null)
+    if (!stat) return null
+    const raw = await fs.promises.readFile(LOCK_PATH, 'utf8').catch(() => '')
+    let owner = null
+    try { owner = JSON.parse(raw) } catch { }
+    const generation = typeof owner?.token === 'string' && /^[a-f0-9-]{36}$/i.test(owner.token)
+        ? owner.token.toLowerCase()
+        : `legacy-${crypto.createHash('sha256')
+            .update(`${raw}\0${stat.dev}\0${stat.ino}\0${stat.mtimeMs}\0${stat.size}`)
+            .digest('hex')}`
+    return { stat, owner, generation }
+}
+
+/** @param {{stat:fs.Stats,owner:any}} state */
+function isStaleFileLock(state) {
+    return Date.now() - state.stat.mtimeMs > LOCK_STALE_MS
+        && !processAlive(Number(state.owner?.pid), state.owner?.identity)
+}
+
+/**
+ * A token-specific reap file elects one cleanup owner for a stale lock
+ * generation. A crashed reaper fails closed for that generation instead of
+ * letting a second process unlink a newly-created lock.
+ */
+async function reapStaleFileLock() {
+    const observed = await readFileLockState()
+    if (!observed || !isStaleFileLock(observed)) return false
+    const reapPath = `${LOCK_REAP_PREFIX}${observed.generation}`
+    let reapHandle
+    try {
+        reapHandle = await fs.promises.open(reapPath, 'wx', 0o600)
+        await reapHandle.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }))
+        await reapHandle.sync()
+    } catch (error) {
+        if (reapHandle) {
+            await reapHandle.close().catch(() => {})
+            await fs.promises.rm(reapPath, { force: true }).catch(() => {})
+        }
+        if (/** @type {any} */ (error)?.code === 'EEXIST') return false
+        throw error
+    }
+
+    try {
+        const current = await readFileLockState()
+        if (!current || current.generation !== observed.generation || !isStaleFileLock(current)) return false
+        await fs.promises.unlink(LOCK_PATH).catch(error => {
+            if (/** @type {any} */ (error)?.code !== 'ENOENT') throw error
+        })
+        return true
+    } finally {
+        await reapHandle.close().catch(() => {})
+        await fs.promises.rm(reapPath, { force: true }).catch(() => {})
+    }
+}
+
+async function acquireFileLock() {
+    migrateLegacyThemeDirectories()
+    await fs.promises.mkdir(themesDir, { recursive: true, mode: 0o700 })
+    const started = Date.now()
+    while (Date.now() - started < LOCK_WAIT_MS) {
+        let handle
+        try {
+            handle = await fs.promises.open(LOCK_PATH, 'wx', 0o600)
+            const token = crypto.randomUUID()
+            try {
+                await handle.writeFile(JSON.stringify({
+                    pid: process.pid,
+                    identity: currentProcessStartIdentity(),
+                    token,
+                    createdAt: new Date().toISOString(),
+                }))
+                await handle.sync()
+                return { handle, token }
+            } catch (error) {
+                await handle.close().catch(() => {})
+                await fs.promises.rm(LOCK_PATH, { force: true }).catch(() => {})
+                throw error
+            }
+        } catch (error) {
+            if (/** @type {any} */ (error)?.code !== 'EEXIST') throw error
+            if (await reapStaleFileLock()) continue
+            await wait(200)
+        }
+    }
+    throw new ThemeMarketClientError('theme_install_busy')
+}
+
+/** @template T @param {() => Promise<T>} operation @returns {Promise<T>} */
+export async function withMarketInstallLock(operation) {
+    if (installLockContext.getStore()) return operation()
+    const previous = processQueue.catch(() => {})
+    /** @type {() => void} */
+    let releaseQueue = () => {}
+    processQueue = new Promise(resolve => { releaseQueue = () => resolve() })
+    await previous
+    let lock
+    try {
+        lock = await acquireFileLock()
+        return await installLockContext.run(lock, operation)
+    } finally {
+        if (lock) {
+            await lock.handle.close().catch(() => {})
+            const current = await readFileLockState()
+            if (current?.owner?.token === lock.token) {
+                await fs.promises.rm(LOCK_PATH, { force: true }).catch(() => {})
+            }
+        }
+        releaseQueue()
+    }
+}
+
+export const marketInstallLockPath = LOCK_PATH