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:
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 }
|
||||
}
|
||||
@@ -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.
|
||||
|
||||
@@ -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. */
|
||||
|
||||
Reference in new issue
Block a user