feat(plugin-detail): show Markdown plugin details on bundle and market entry pages

Plugins bundle pages and Discover entry pages show the plugin's long
description first, as Markdown with images, in a height-limited region
without its own heading. The document is the file locale meta.detail
names, otherwise the package README, otherwise (market entries only)
the declared repository's README.

The new dsh-plugin-detail library selects documents and reads local
package directories and npm file CDNs without state. plugin-manager
reads installed and offered bundles through readBundleDetail; plugin-market
reads market entries through readEntryDetail, single-file APIs, and a
size-limited partial clone cache serialized across processes. Raw HTML is
omitted, relative links stay text, and relative images load from Host
routes with a sandbox CSP.
This commit is contained in:
turtle1999 committed 2026-10-19 19:13:22 +08:00
1 parent 82a5ae1744
commit 9c8522bb64
111 files changed
+5057 -141

No files matched your search

@@ -0,0 +1,104 @@
/**
* Detail documents of profile bundles: an installed bundle's `meta.detail` file or README from its directory, and an
* official bundle the installation offers, before it is installed, from the npm file CDNs at its offered version. Reads
* keep no state; an image request resolves its bundle and document again.
*/
import semver from 'semver'
import { resolveBundleDir } from '@deepseek-ai/dsh-app-boot'
import type { ProfileContext } from '@deepseek-ai/dsh-app-boot'
import {
DetailFailure, detailImage, languageChain, localFiles, npmFileSourceOrder, npmFiles, readPackageDocument,
type DetailFiles, type NpmFileSource,
} from '@deepseek-ai/dsh-plugin-detail'
import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
import type { BundleDetail, BundleInfo } from './types.ts'
/** Limits and sources of bundle detail reads. */
export interface BundleDetailOptions {
readonly profile: ProfileContext
readonly maxDocumentBytes: number
readonly maxImageBytes: number
readonly npmFileSources: readonly NpmFileSource[]
/** Deadline of one CDN request. */
readonly timeoutMs: number
/** The plugin manager's disposal. */
readonly lifetime: AbortSignal
}
/**
* The files of a listed bundle: its directory when its files can be read, otherwise its offered npm version.
* @param bundle - the bundle as `listBundles()` reports it.
* @param preferred - npm file CDNs to ask first for an offered version; see `npmFileSourceOrder`.
* @param options - profile, sources, and limits.
* @returns the files, or undefined for a bundle offered at no published version.
* @throws {RemoteError} `plugin-manager/unknown-bundle` when the bundle's directory cannot be resolved.
*/
function filesOf(bundle: BundleInfo, preferred: readonly string[], options: BundleDetailOptions): DetailFiles | undefined {
if (bundle.availability !== 'missing') {
let dir: string
try {
dir = resolveBundleDir('dsh', bundle.name, options.profile.installAnchor, options.profile.dir)
} catch (error) {
throw new RemoteError('plugin-manager/unknown-bundle', (error as Error).message, { name: bundle.name }, { cause: error })
}
// `listBundles()` reports the version of every bundle whose manifest it read; one without is read as unversioned.
return localFiles(dir, String(bundle.version))
}
const version = bundle.installTarget?.version
if (version === undefined || semver.valid(version) !== version) return undefined
const sources = npmFileSourceOrder(options.npmFileSources, preferred)
return npmFiles(bundle.name, version, sources, { timeoutMs: options.timeoutMs, lifetime: options.lifetime })
}
/** Rethrow a detail failure as the Remote error clients read. */
function remoteFailure(error: unknown): never {
if (error instanceof DetailFailure) {
throw new RemoteError('plugin-manager/detail-unavailable', error.message, { reason: error.reason }, { cause: error })
}
throw error
}
/**
* Read a bundle's detail document in a display language.
* @param bundle - the bundle as `listBundles()` reports it.
* @param language - a BCP 47 language id.
* @param preferred - npm file CDNs to ask first for an offered version; see `npmFileSourceOrder`.
* @param options - profile, sources, and limits.
* @returns the document, or `none` when the bundle has neither a `meta.detail` file nor a README.
* @throws {RemoteError} `plugin-manager/invalid-language`, `plugin-manager/unknown-bundle`, or
* `plugin-manager/detail-unavailable`.
*/
export async function readBundleDocument(
bundle: BundleInfo, language: string, preferred: readonly string[], options: BundleDetailOptions,
): Promise<BundleDetail> {
let languages: string[]
try {
languages = languageChain(language)
} catch (error) {
throw new RemoteError('plugin-manager/invalid-language', (error as Error).message, { language }, { cause: error })
}
const files = filesOf(bundle, preferred, options)
if (files === undefined) return { status: 'none' }
const document = await readPackageDocument(files, '', languages, options.maxDocumentBytes, options.lifetime).catch(remoteFailure)
return document === undefined ? { status: 'none' } : { status: 'found', ...document }
}
/**
* Read an image beside a bundle's detail document.
* @param bundle - the bundle as `listBundles()` reports it.
* @param document - the document's path inside the bundle, as {@link readBundleDocument} returned it.
* @param destination - the image destination as the document writes it.
* @param preferred - npm file CDNs to ask first for an offered version; see `npmFileSourceOrder`.
* @param options - profile, sources, and limits.
* @returns the bytes and media type, or undefined for a path outside the bundle, an unsupported type, or a missing file.
* @throws {RemoteError} `plugin-manager/unknown-bundle` or `plugin-manager/detail-unavailable`.
*/
export async function readBundleImage(
bundle: BundleInfo, document: string, destination: string, preferred: readonly string[], options: BundleDetailOptions,
): Promise<{ bytes: Uint8Array; mediaType: string } | undefined> {
const image = detailImage(document, destination)
const files = image === undefined ? undefined : filesOf(bundle, preferred, options)
if (image === undefined || files === undefined) return undefined
const bytes = await files.read(image.path, options.maxImageBytes, options.lifetime).catch(remoteFailure)
return bytes === undefined ? undefined : { bytes, mediaType: image.mediaType }
}
+78 -3
View File
@@ -10,7 +10,12 @@ import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
import z from '@deepseek-ai/schemastery'
import semver from 'semver'
import { TypertRemoteService, Remote } from '@deepseek-ai/dsh-typert-protocol'
import { TypertRemoteService, Remote, RemoteError, remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol'
import { detailImageResponse, NPM_FILE_SOURCES } from '@deepseek-ai/dsh-plugin-detail'
import type { NpmFileSource } from '@deepseek-ai/dsh-plugin-detail/types'
import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
import type {} from '@deepseek-ai/dsh-client-connection'
import { readBundleDocument, readBundleImage, type BundleDetailOptions } from './bundle-detail.ts'
import { pluginEntryId, readPluginInventory } from '@deepseek-ai/dsh-host-plugin-inventory'
import {
readPluginMeta, readProfileManifest, resolveBundleDir, loadOverlayPatches, composeEntries,
@@ -32,8 +37,8 @@ import { approveBuilds, recordPendingBuilds } from './build-approval.ts'
import { checkGithubConnection } from './github-connection.ts'
import { newerVersions, VERSION_FIELDS, VERSION_LIST_FIELDS, versionFacts } from './versions.ts'
import type {
BundleInfo, BundleRowInfo, ChangeResult, InspectOptions, InstallBundleOptions, ListVersionsOptions, ManagementError, PackageResult,
PluginChange, PluginEntryId, PluginInfo, PluginInstallCancellation, PluginInstallProgress, PluginInstallRequestId,
BundleDetail, BundleInfo, BundleRowInfo, ChangeResult, InspectOptions, InstallBundleOptions, ListVersionsOptions, ManagementError,
PackageResult, PluginChange, PluginEntryId, PluginInfo, PluginInstallCancellation, PluginInstallProgress, PluginInstallRequestId,
PluginRegistries, PluginSpecInspection, PluginUpdateResult, PluginUpdateStep, PluginVersion, PluginVersionList, Registry,
RegistryAttempt, UpdateBundleOptions,
} from './types.ts'
@@ -67,8 +72,19 @@ export interface Config {
versionListLimit?: number
/** How many single-version registry lookups a version listing runs at once. */
versionLookupConcurrency?: number
/** Largest bundle detail document, and largest locale file read for one, in bytes. */
detailMaxBytes?: number
/** Largest image served beside a bundle detail document, in bytes. */
detailImageMaxBytes?: number
/** Deadline of one npm file CDN request for an offered bundle's detail document. */
detailFetchTimeoutMs?: number
/** npm file CDNs that offered bundles are read from, in order; a read's `npmFileSources` moves the CDNs it names first. */
detailNpmFileSources?: NpmFileSource[]
}
/** The Fetch route serving images beside bundle detail documents. */
const DETAIL_FILE_PATH = '/api/plugin-manager/detail-file'
/** An http(s) URL, as pnpm's `--registry` takes it. */
const REGISTRY_URL = /^https?:\/\/\S+$/
@@ -288,6 +304,10 @@ export class PluginManager extends TypertRemoteService {
fallbackRegistries: z.array(z.string().pattern(REGISTRY_URL)).default([NPMMIRROR_REGISTRY]),
versionListLimit: z.number().step(1).min(1).default(20),
versionLookupConcurrency: z.number().step(1).min(1).default(4),
detailMaxBytes: z.natural().min(1).default(1024 * 1024),
detailImageMaxBytes: z.natural().min(1).default(5 * 1024 * 1024),
detailFetchTimeoutMs: z.natural().min(1).max(MAX_TIMER_DELAY_MS).default(15000),
detailNpmFileSources: z.array(z.union(NPM_FILE_SOURCES)).min(1).default([...NPM_FILE_SOURCES]),
})
/** Management bundles remain protected if their files become unreadable. */
private readonly managementBundles = new Set<string>()
@@ -312,6 +332,7 @@ export class PluginManager extends TypertRemoteService {
private readonly abort = new AbortController()
/** Installations by request id, from their call until it settles. */
private readonly installs = new Map<PluginInstallRequestId, InstallControl>()
private readonly detail: BundleDetailOptions
constructor(ctx: Context, config: Config) {
super(ctx, 'pluginManager')
@@ -331,10 +352,64 @@ export class PluginManager extends TypertRemoteService {
registry: config.registry === undefined ? null : normalizeRegistry(config.registry),
fallbackRegistries: (config as Required<Config>).fallbackRegistries.map(normalizeRegistry),
}
const required = config as Required<Config>
this.detail = {
profile: this.profile, maxDocumentBytes: required.detailMaxBytes, maxImageBytes: required.detailImageMaxBytes,
npmFileSources: required.detailNpmFileSources, timeoutMs: required.detailFetchTimeoutMs, lifetime: this.abort.signal,
}
ctx.effect(() => async () => {
this.abort.abort()
await Promise.allSettled([...this.packageOperations])
}, 'plugin-manager: package cancellation')
ctx.inject(['connection'], (scope) => {
scope.effect(() => scope.connection.fetch.register({
path: DETAIL_FILE_PATH, methods: ['GET'], requestBody: 'buffered', fetch: request => this.serveDetailFile(request),
}), `plugin-manager: ${DETAIL_FILE_PATH}`)
})
}
/**
* Read a bundle's long description: the Markdown file its locale `meta.detail` names in `language`, otherwise its
* README. An installed bundle is read from its directory without network access; an official bundle the installation
* offers before it is installed is read from the npm file CDNs at its offered version. Nothing is cached.
* @param name - the bundle's package name, as `listBundles()` lists it.
* @param language - the display language, such as `zh-CN`; documents fall back through its prefixes to English.
* @param options - `npmFileSources` names npm file CDNs to ask first for an offered bundle, in order, such as the one
* a Client measured as fastest; configured CDNs it omits follow, and CDNs that are not configured are not asked.
* @returns the document with its origin and path, or `none`.
* @throws {RemoteError} `plugin-manager/unknown-bundle`, `plugin-manager/invalid-language`, or
* `plugin-manager/detail-unavailable`.
*/
@Remote
async readBundleDetail(name: string, language: string, options?: { npmFileSources?: NpmFileSource[] }): Promise<BundleDetail> {
return await readBundleDocument(await this.listedBundle(name), language, options?.npmFileSources ?? [], this.detail)
}
private async listedBundle(name: string): Promise<BundleInfo> {
const bundle = (await this.listBundles()).find(candidate => candidate.name === name)
if (bundle === undefined) throw new RemoteError('plugin-manager/unknown-bundle', `No such bundle: ${name}`, { name })
return bundle
}
/**
* Answer `GET ${DETAIL_FILE_PATH}?bundle=<name>&document=<path>&path=<destination>[&sources=<cdn>,...]` with one image
* beside a bundle document; `sources` names npm file CDNs to ask first for an offered bundle, as `readBundleDetail` does.
*/
private async serveDetailFile(request: Request): Promise<Response> {
const params = new URL(request.url).searchParams
const [bundle, document, path] = [params.get('bundle'), params.get('document'), params.get('path')]
// Images are read again on every request, so a reinstalled bundle shows its own.
const cache = 'no-store'
if (bundle === null || document === null || path === null) return detailImageResponse('invalid', cache)
try {
const image = await readBundleImage(await this.listedBundle(bundle), document, path, params.get('sources')?.split(',') ?? [], this.detail)
return detailImageResponse(image, cache)
} catch (error) {
const failure = remoteErrorOf(error)
if (failure?.code === 'plugin-manager/unknown-bundle') return detailImageResponse(undefined, cache)
if (failure?.code === 'plugin-manager/detail-unavailable') return detailImageResponse(failure.details.reason, cache)
throw error
}
}
/** Read exact plugin-version exemptions saved in this profile.
+33
View File
@@ -4,6 +4,23 @@ import type { PluginLocalizedMeta } from '@deepseek-ai/dsh-package-manifest'
import type { PluginInventoryEntry } from '@deepseek-ai/dsh-host-plugin-inventory/types'
export type { PluginEntryId } from '@deepseek-ai/dsh-host-plugin-inventory/types'
import type { PluginEntryId } from '@deepseek-ai/dsh-host-plugin-inventory/types'
import type {} from '@deepseek-ai/dsh-typert-protocol'
import type { DetailFailureReason } from '@deepseek-ai/dsh-plugin-detail/types'
declare module '@deepseek-ai/dsh-typert-protocol' {
interface RemoteErrorDetailsMap {
/** The profile lists no such bundle, or its directory cannot be resolved. */
'plugin-manager/unknown-bundle': { readonly name: string }
/** The display language is not a BCP 47 language id. */
'plugin-manager/invalid-language': { readonly language: string }
/**
* A bundle's detail document or image exists but cannot be read: `too-large` beyond a size limit, `network` when the
* npm file CDNs cannot be reached, `invalid` for a malformed locale file or `meta.detail`, or a named file that does
* not exist. Bundle files come from local directories and public CDNs, which never answer `denied`.
*/
'plugin-manager/detail-unavailable': { readonly reason: DetailFailureReason }
}
}
/** Reasons a profile control cannot modify its target. */
export type ReadOnlyReason = 'management-required' | 'unaddressable'
@@ -341,6 +358,22 @@ export interface PluginInstallLogChunk {
readonly exitCode?: number | null
}
/**
* A bundle's long description, or `none` when it has neither a `meta.detail` file nor a README. Images resolve beside
* `path` through `GET /api/plugin-manager/detail-file?bundle=<name>&document=<path>&path=<destination>`.
*/
export type BundleDetail =
| {
readonly status: 'found'
/** `locale` for the file locale `meta.detail` names, `readme` for the package's README. */
readonly origin: 'locale' | 'readme'
/** `/`-separated path of the document inside the package. */
readonly path: string
/** Markdown text without a byte order mark or a leading YAML front matter block. */
readonly markdown: string
}
| { readonly status: 'none' }
/** What changed in the profile, for consumers that show it. */
export interface PluginChange {
/** The operation that changed it. */