@lingxi-ai-cn/dsh-plugin-hub 0.1.0-rc.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @lingxi-ai-cn/dsh-plugin-hub
+
+English | [中文](README.zh.md)
+
+Provider-neutral human Plugin Hub capability exposed as `ctx.pluginHub`. The service owns stable catalog, installed-state, detached-plan, staging, and activation-handoff DTOs plus provider registration, transient progress events, the error taxonomy, and an explicit `supportsProfileMutations()` capability. HTTP, cache, signatures, profile mutation, package-manager work, journals, and maintenance processes belong to providers. A catalog-only provider reports `false`, so a consumer can keep discovery and installed truth active without presenting an in-process mutation action.
+
+Catalog detail DTOs preserve repository archive state, declared and verified operating systems, bounded curation notes, and structured advisories with severity and recommended action. These are discovery and risk-display facts; none can establish installability or replace signed descriptor verification.
+
+Catalog rows may also carry Registry-owned categories, package kind, metadata source, and repository primary language. These fields are presentation and optional search filters only; clients do not infer them from README text, descriptions, repository names, or popularity.
+
+Catalog search accepts provider-neutral `relevance`, `stars`, `updated`, and `newest` ordering. Providers keep continuation cursors opaque and bind them to the complete request, including ordering; catalog ordering remains human discovery state and does not affect installability or verification.
+
+Install planning accepts only opaque `PluginId` and `PluginVersionId` values. Plans expose exact confirmation facts but never artifact URLs, local paths, executables, package-manager arguments, or a signature bypass. Staging and activation accept only provider-issued branded ids, and `markMaintenanceReady()` is a no-op outside an authenticated relaunch handoff.
+
+## Model Experience
+
+None, as the service exposes catalog rows, README text, and progress only to human UI consumers and never writes them to the Session log.
+
+#### KV Cache effect
+
+No effect; the service does not add, replace, or retain model-request content.
+
+## Known Limitations and Deferred Work
+
+- **Provider implementation required** - the Service Definition performs no Registry verification or profile mutation by itself; the mounted Host provider owns every trust and transaction decision.
+- **No rollback contract** - retained generations, history, rollback planning, and advisory remediation remain outside the initial install lifecycle.

package/README.zh.md

@@ -0,0 +1,26 @@
+# @lingxi-ai-cn/dsh-plugin-hub
+
+中文 | [English](README.md)
+
+这是通过 `ctx.pluginHub` 提供的 provider-neutral 人工 Plugin Hub 能力。服务拥有稳定的目录、installed state、detached plan、staging 和 activation handoff DTO，以及 provider 注册、临时 progress event、错误分类和显式 `supportsProfileMutations()` capability；HTTP、cache、signature、profile 修改、包管理器、journal 和 maintenance process 都属于 provider。只提供目录的 provider 会报告 `false`，因此 consumer 可以继续提供发现与已安装事实，而不呈现进程内修改操作。
+
+目录详情 DTO 会保留 repository archive 状态、声明与验证过的 operating system、有界 curation note，以及带 severity 与 recommended action 的结构化 advisory。这些只是发现和风险展示事实；任何一项都不能确立 installability，也不能替代 signed descriptor 校验。
+
+目录 row 还可以携带由 Registry 提供的 category、package kind、metadata source 和 repository primary language。这些字段只用于展示和可选搜索筛选；client 不会从 README text、description、repository name 或 popularity 推断它们。
+
+目录 search 接受 provider-neutral 的 `relevance`、`stars`、`updated` 和 `newest` ordering。provider 会保持 continuation cursor opaque，并将其绑定到包含 ordering 在内的完整 request；目录 ordering 只属于人工发现 state，不会影响 installability 或 verification。
+
+安装计划只接受 opaque `PluginId` 和 `PluginVersionId`。plan 公开精确确认事实，但绝不公开 artifact URL、本地路径、executable、包管理器参数或 signature bypass。staging 和 activation 只接受 provider 签发的 branded id；`markMaintenanceReady()` 在 authenticated relaunch handoff 之外是 no-op。
+
+## Model Experience
+
+无，因为该服务只向人工 UI consumer 提供目录、README 和进度，并且绝不会将它们写入 Session log。
+
+#### KV Cache effect
+
+无影响；该服务不会添加、替换或保留模型请求内容。
+
+## Known Limitations and Deferred Work
+
+- **需要 provider 实现** — Service Definition 自身不执行 Registry 校验或 profile 修改；挂载的 Host provider 拥有全部 trust 和 transaction decision。
+- **无 rollback contract** — generation 保留、history、rollback plan 和 advisory remediation 不属于首个安装 lifecycle。

package/lib/index.js

@@ -0,0 +1,197 @@
+import { Service } from "@deepseek-ai/cordis";
+//#region lib/types/types.js
+/** Provider-neutral Plugin Hub catalog vocabulary. */
+/**
+* Brand a catalog plugin id received from a provider.
+* @param value - provider-issued opaque id.
+* @returns the same string with the PluginId brand.
+*/
+function PluginId(value) {
+	return value;
+}
+/**
+* Brand a catalog version id received from a provider.
+* @param value - provider-issued opaque id.
+* @returns the same string with the PluginVersionId brand.
+*/
+function PluginVersionId(value) {
+	return value;
+}
+/**
+* Brand a provider-issued detached plan id.
+* @param value - provider-issued opaque id.
+* @returns the same string with the PluginChangePlanId brand.
+*/
+function PluginChangePlanId(value) {
+	return value;
+}
+/**
+* Brand a provider-issued transaction id.
+* @param value - provider-issued opaque id.
+* @returns the same string with the PluginTransactionId brand.
+*/
+function PluginTransactionId(value) {
+	return value;
+}
+/** Stable wire/API version currently understood by the local consumer. */
+const PLUGIN_HUB_API_VERSION = "dsh.plugin-hub/v1";
+/** Typed failure that callers can branch on without parsing a message. */
+var PluginHubError = class extends Error {
+	/** Stable category consumed by UI and retry policy. */
+	code;
+	/**
+	* @param message - bounded public diagnostic.
+	* @param code - stable machine-readable category.
+	* @param options - optional underlying cause.
+	*/
+	constructor(message, code, options) {
+		super(message, options);
+		this.name = "PluginHubError";
+		this.code = code;
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/** Plugin Hub Service Definition for read-only catalog consumers. */
+/** Read-only provider registry and facade consumed by native TUI. */
+var PluginHubRuntime = class extends Service {
+	providers = /* @__PURE__ */ new Map();
+	constructor(ctx) {
+		super(ctx, "pluginHub");
+	}
+	/**
+	* Register one provider; the effect owns removal on unload.
+	* @param provider - provider implementation for this fiber.
+	* @returns disposer that removes the exact registration.
+	*/
+	registerProvider(provider) {
+		if (this.providers.size > 0) throw new Error("a plugin hub provider is already registered");
+		const dispose = this.ctx.effect(function* () {
+			this.providers.set(provider.id, provider);
+			yield () => {
+				this.providers.delete(provider.id);
+			};
+		}.bind(this), "pluginHub.registerProvider()");
+		return () => {
+			dispose();
+		};
+	}
+	/**
+	* Inspect provider availability without starting I/O.
+	* @returns whether at least one provider is mounted for optional consumers.
+	*/
+	hasProvider() {
+		return this.providers.size > 0;
+	}
+	/**
+	* Inspect whether the mounted provider may mutate the active profile.
+	* Missing providers and catalog-only providers both return false.
+	* @returns provider-declared profile mutation capability.
+	*/
+	supportsProfileMutations() {
+		const [provider] = this.providers.values();
+		return provider?.profileMutations === true;
+	}
+	/** Return the one configured provider or a stable unavailable error. */
+	provider() {
+		const [provider] = this.providers.values();
+		if (provider === void 0) throw new PluginHubError("No Plugin Hub provider is configured.", "REGISTRY_UNAVAILABLE");
+		return provider;
+	}
+	/**
+	* Read provider health and catalog freshness.
+	* @param signal - optional caller cancellation signal.
+	* @returns provider status.
+	*/
+	async status(signal) {
+		return this.provider().status(signal);
+	}
+	/**
+	* Search the bounded catalog.
+	* @param request - literal search and filter request.
+	* @param signal - optional caller cancellation signal.
+	* @returns one provider page.
+	*/
+	async search(request, signal) {
+		return this.provider().search(request, signal);
+	}
+	/**
+	* Load one complete read-only plugin description.
+	* @param pluginId - opaque catalog plugin id.
+	* @param signal - optional caller cancellation signal.
+	* @returns one provider detail record.
+	*/
+	async plugin(pluginId, signal) {
+		return this.provider().plugin(pluginId, signal);
+	}
+	/**
+	* Inspect profile-local installed truth.
+	* @param signal - optional caller cancellation signal.
+	* @returns exact active-profile revision, bundle order, and third-party dependencies.
+	*/
+	async installed(signal) {
+		return this.provider().installed(signal);
+	}
+	/**
+	* Verify one selected Registry version and create a detached install or update plan.
+	* @param pluginId - opaque selected plugin id.
+	* @param versionId - opaque selected version id.
+	* @param signal - optional caller cancellation signal.
+	* @returns expiring plan containing only user-confirmation facts.
+	*/
+	async planInstall(pluginId, versionId, signal) {
+		return this.provider().planInstall(pluginId, versionId, signal);
+	}
+	/**
+	* Create a detached removal plan from local installed truth.
+	* @param packageName - exact installed dependency name.
+	* @param signal - optional caller cancellation signal.
+	* @returns expiring local removal plan.
+	*/
+	async planRemove(packageName, signal) {
+		return this.provider().planRemove(packageName, signal);
+	}
+	/**
+	* Prepare a still-current plan in an inactive staging generation.
+	* @param planId - provider-issued detached plan id.
+	* @param signal - optional caller cancellation signal.
+	* @returns durable staged transaction; the active profile is unchanged.
+	*/
+	async stage(planId, signal) {
+		return this.provider().stage(planId, signal);
+	}
+	/**
+	* Discard one pre-activation transaction.
+	* @param transactionId - provider-issued transaction id.
+	* @param signal - optional caller cancellation signal.
+	*/
+	async discard(transactionId, signal) {
+		await this.provider().discard(transactionId, signal);
+	}
+	/**
+	* Transfer a staged transaction to the maintenance process.
+	* @param transactionId - provider-issued staged transaction id.
+	* @param signal - optional caller cancellation signal.
+	* @returns handoff state after the maintenance process starts waiting.
+	*/
+	async createMaintenanceHandoff(transactionId, signal) {
+		return this.provider().createMaintenanceHandoff(transactionId, signal);
+	}
+	/**
+	* Publish the exact maintenance ready marker after the relaunched TUI mounts.
+	* A normal boot without a handoff is a no-op.
+	* @param signal - optional caller cancellation signal.
+	*/
+	async markMaintenanceReady(signal) {
+		await this.provider().markMaintenanceReady(signal);
+	}
+	/**
+	* Publish transient provider progress to in-process UI listeners.
+	* @param progress - bounded public progress update.
+	*/
+	publishProgress(progress) {
+		this.ctx.emit("plugin-hub/progress", progress);
+	}
+};
+//#endregion
+export { PLUGIN_HUB_API_VERSION, PluginChangePlanId, PluginHubError, PluginHubRuntime, PluginHubRuntime as default, PluginId, PluginTransactionId, PluginVersionId };

package/lib/invariant.js

@@ -0,0 +1,11 @@
+//#region lib/types/invariant.js
+/** Package-owned invariant companion for the Plugin Hub Service Definition. */
+const PACKAGE_NAME = "@lingxi-ai-cn/dsh-plugin-hub";
+const name = "plugin-hub-invariant";
+const inject = ["invariants"];
+/** No runtime invariant: provider registrations are private and effects own their disposal. */
+const install = () => {};
+/** Register this package's invariant companion. */
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,115 @@
+/** Plugin Hub Service Definition for read-only catalog consumers. */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { InstalledPluginSnapshot, PluginChangePlan, PluginChangePlanId, PluginDetail, PluginHubProgress, PluginHubProvider, PluginHubStatus, PluginId, PluginMaintenanceHandoff, PluginSearchPage, PluginSearchRequest, PluginTransactionId, PluginVersionId, StagedPluginTransaction } from './types.ts';
+export * from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        pluginHub: PluginHubRuntime;
+    }
+    interface Events {
+        /**
+         * Provider progress is transient UI state and is never durable.
+         * @param progress - bounded public progress.
+         * @mode emit
+         */
+        'plugin-hub/progress'(progress: PluginHubProgress): void;
+    }
+}
+/** Read-only provider registry and facade consumed by native TUI. */
+export declare class PluginHubRuntime extends Service {
+    private readonly providers;
+    constructor(ctx: Context);
+    /**
+     * Register one provider; the effect owns removal on unload.
+     * @param provider - provider implementation for this fiber.
+     * @returns disposer that removes the exact registration.
+     */
+    registerProvider(provider: PluginHubProvider): () => void;
+    /**
+     * Inspect provider availability without starting I/O.
+     * @returns whether at least one provider is mounted for optional consumers.
+     */
+    hasProvider(): boolean;
+    /**
+     * Inspect whether the mounted provider may mutate the active profile.
+     * Missing providers and catalog-only providers both return false.
+     * @returns provider-declared profile mutation capability.
+     */
+    supportsProfileMutations(): boolean;
+    /** Return the one configured provider or a stable unavailable error. */
+    private provider;
+    /**
+     * Read provider health and catalog freshness.
+     * @param signal - optional caller cancellation signal.
+     * @returns provider status.
+     */
+    status(signal?: AbortSignal): Promise<PluginHubStatus>;
+    /**
+     * Search the bounded catalog.
+     * @param request - literal search and filter request.
+     * @param signal - optional caller cancellation signal.
+     * @returns one provider page.
+     */
+    search(request: PluginSearchRequest, signal?: AbortSignal): Promise<PluginSearchPage>;
+    /**
+     * Load one complete read-only plugin description.
+     * @param pluginId - opaque catalog plugin id.
+     * @param signal - optional caller cancellation signal.
+     * @returns one provider detail record.
+     */
+    plugin(pluginId: PluginId, signal?: AbortSignal): Promise<PluginDetail>;
+    /**
+     * Inspect profile-local installed truth.
+     * @param signal - optional caller cancellation signal.
+     * @returns exact active-profile revision, bundle order, and third-party dependencies.
+     */
+    installed(signal?: AbortSignal): Promise<InstalledPluginSnapshot>;
+    /**
+     * Verify one selected Registry version and create a detached install or update plan.
+     * @param pluginId - opaque selected plugin id.
+     * @param versionId - opaque selected version id.
+     * @param signal - optional caller cancellation signal.
+     * @returns expiring plan containing only user-confirmation facts.
+     */
+    planInstall(pluginId: PluginId, versionId: PluginVersionId, signal?: AbortSignal): Promise<PluginChangePlan>;
+    /**
+     * Create a detached removal plan from local installed truth.
+     * @param packageName - exact installed dependency name.
+     * @param signal - optional caller cancellation signal.
+     * @returns expiring local removal plan.
+     */
+    planRemove(packageName: string, signal?: AbortSignal): Promise<PluginChangePlan>;
+    /**
+     * Prepare a still-current plan in an inactive staging generation.
+     * @param planId - provider-issued detached plan id.
+     * @param signal - optional caller cancellation signal.
+     * @returns durable staged transaction; the active profile is unchanged.
+     */
+    stage(planId: PluginChangePlanId, signal?: AbortSignal): Promise<StagedPluginTransaction>;
+    /**
+     * Discard one pre-activation transaction.
+     * @param transactionId - provider-issued transaction id.
+     * @param signal - optional caller cancellation signal.
+     */
+    discard(transactionId: PluginTransactionId, signal?: AbortSignal): Promise<void>;
+    /**
+     * Transfer a staged transaction to the maintenance process.
+     * @param transactionId - provider-issued staged transaction id.
+     * @param signal - optional caller cancellation signal.
+     * @returns handoff state after the maintenance process starts waiting.
+     */
+    createMaintenanceHandoff(transactionId: PluginTransactionId, signal?: AbortSignal): Promise<PluginMaintenanceHandoff>;
+    /**
+     * Publish the exact maintenance ready marker after the relaunched TUI mounts.
+     * A normal boot without a handoff is a no-op.
+     * @param signal - optional caller cancellation signal.
+     */
+    markMaintenanceReady(signal?: AbortSignal): Promise<void>;
+    /**
+     * Publish transient provider progress to in-process UI listeners.
+     * @param progress - bounded public progress update.
+     */
+    publishProgress(progress: PluginHubProgress): void;
+}
+export default PluginHubRuntime;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,7 @@
+/** Package-owned invariant companion for the Plugin Hub Service Definition. */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "plugin-hub-invariant";
+export declare const inject: string[];
+/** Register this package's invariant companion. */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,257 @@
+/** Provider-neutral Plugin Hub catalog vocabulary. */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+/** Exact opaque identifier assigned to one catalog plugin. */
+export type PluginId = Branded<'PluginId'>;
+/**
+ * Brand a catalog plugin id received from a provider.
+ * @param value - provider-issued opaque id.
+ * @returns the same string with the PluginId brand.
+ */
+export declare function PluginId(value: string): PluginId;
+/** Exact opaque identifier assigned to one published plugin version. */
+export type PluginVersionId = Branded<'PluginVersionId'>;
+/**
+ * Brand a catalog version id received from a provider.
+ * @param value - provider-issued opaque id.
+ * @returns the same string with the PluginVersionId brand.
+ */
+export declare function PluginVersionId(value: string): PluginVersionId;
+/** Opaque identifier for one detached local profile change plan. */
+export type PluginChangePlanId = Branded<'PluginChangePlanId'>;
+/**
+ * Brand a provider-issued detached plan id.
+ * @param value - provider-issued opaque id.
+ * @returns the same string with the PluginChangePlanId brand.
+ */
+export declare function PluginChangePlanId(value: string): PluginChangePlanId;
+/** Opaque identifier for one durable local profile transaction. */
+export type PluginTransactionId = Branded<'PluginTransactionId'>;
+/**
+ * Brand a provider-issued transaction id.
+ * @param value - provider-issued opaque id.
+ * @returns the same string with the PluginTransactionId brand.
+ */
+export declare function PluginTransactionId(value: string): PluginTransactionId;
+/** Stable wire/API version currently understood by the local consumer. */
+export declare const PLUGIN_HUB_API_VERSION: "dsh.plugin-hub/v1";
+/** Public error taxonomy shared by providers and TUI consumers. */
+export type PluginHubErrorCode = 'REGISTRY_UNAVAILABLE' | 'CATALOG_STALE' | 'CONTRACT_UNSUPPORTED' | 'SIGNATURE_INVALID' | 'DESCRIPTOR_EXPIRED' | 'PLUGIN_NOT_FOUND' | 'VERSION_NOT_INSTALLABLE' | 'DSH_INCOMPATIBLE' | 'SURFACE_INCOMPATIBLE' | 'PLUGIN_QUARANTINED' | 'ARTIFACT_TOO_LARGE' | 'ARTIFACT_DIGEST_MISMATCH' | 'PROFILE_BUSY' | 'PROFILE_CHANGED' | 'PNPM_UNAVAILABLE' | 'PNPM_FAILED' | 'BUILD_NOT_ALLOWED' | 'PROFILE_INVALID' | 'PLAN_EXPIRED' | 'STAGE_FAILED' | 'HANDOFF_FAILED' | 'INVALID_CURSOR' | 'OPERATION_ABORTED';
+/** Typed failure that callers can branch on without parsing a message. */
+export declare class PluginHubError extends Error {
+    /** Stable category consumed by UI and retry policy. */
+    readonly code: PluginHubErrorCode;
+    /**
+     * @param message - bounded public diagnostic.
+     * @param code - stable machine-readable category.
+     * @param options - optional underlying cause.
+     */
+    constructor(message: string, code: PluginHubErrorCode, options?: ErrorOptions);
+}
+/** Provider health and last-good catalog state. */
+export interface PluginHubStatus {
+    readonly apiVersion: typeof PLUGIN_HUB_API_VERSION;
+    readonly catalogRevision?: number | undefined;
+    readonly generatedAt?: string | undefined;
+    readonly stale: boolean;
+    readonly source: 'registry' | 'cache' | 'fixture';
+}
+/** Provider-neutral catalog ordering applied by Registry providers. */
+export type PluginCatalogSort = 'relevance' | 'stars' | 'updated' | 'newest';
+/** Registry-owned discovery category; this is presentation metadata, not trust state. */
+export type PluginCategory = 'communication' | 'vision' | 'browser' | 'interface' | 'agent' | 'development' | 'data' | 'automation' | 'integration' | 'theme' | 'other';
+/** Registry-owned package classification used for discovery display. */
+export type PluginPackageKind = 'plugin' | 'bundle' | 'skill' | 'tool' | 'integration';
+/** Authority that supplied one discovery metadata value. */
+export type PluginDiscoveryMetadataSource = 'author' | 'curator' | 'automatic';
+/** Bounded literal catalog search request. */
+export interface PluginSearchRequest {
+    readonly query?: string | undefined;
+    readonly surface?: 'tui' | 'web' | 'headless' | 'unknown' | undefined;
+    readonly dshVersion?: string | undefined;
+    readonly verification?: 'discovered' | 'manifest-valid' | 'install-verified' | 'tui-boot-verified' | 'curated' | undefined;
+    readonly installable?: boolean | undefined;
+    readonly category?: PluginCategory | undefined;
+    readonly kind?: PluginPackageKind | undefined;
+    readonly language?: string | undefined;
+    readonly sort?: PluginCatalogSort | undefined;
+    readonly cursor?: string | undefined;
+    readonly limit?: number | undefined;
+}
+/** Compatibility result returned by the Registry. */
+export interface PluginCompatibility {
+    readonly dsh?: string | undefined;
+    readonly match: 'compatible' | 'incompatible' | 'unknown';
+}
+/** Verification state for one catalog row. */
+export interface PluginVerification {
+    readonly level: 'discovered' | 'manifest-valid' | 'install-verified' | 'tui-boot-verified' | 'curated';
+    readonly status: 'passed' | 'failed' | 'unknown';
+}
+/** Repository identity displayed by the native TUI. */
+export interface PluginRepository {
+    readonly provider: string;
+    readonly providerId?: string;
+    readonly fullName: string;
+    readonly url: string;
+    /** Primary language reported by the repository provider, when available. */
+    readonly primaryLanguage?: string | undefined;
+    /** Whether the source repository is archived and no longer maintained. */
+    readonly archived?: boolean | undefined;
+}
+/** Bounded curation facts supplied by the Registry for human display. */
+export interface PluginCurationSummary {
+    readonly policyRevision: string;
+    readonly notes?: string | undefined;
+    readonly curatedAt: string;
+}
+/** Structured advisory facts supplied by the Registry. */
+export interface PluginAdvisorySummary {
+    readonly id: string;
+    readonly severity: 'low' | 'moderate' | 'high' | 'critical';
+    readonly reason: string;
+    readonly recommendedAction?: string | undefined;
+}
+/** Published version summary shown in Discover and Detail. */
+export interface PluginVersionSummary {
+    readonly id: PluginVersionId;
+    readonly version?: string | undefined;
+    readonly sourceCommit?: string | undefined;
+    readonly publishedAt?: string | undefined;
+    readonly installable: boolean;
+    readonly reason?: string | undefined;
+}
+/** One bounded plugin row in a catalog page. */
+export interface PluginSummary {
+    readonly id: PluginId;
+    readonly packageName: string;
+    readonly displayName: string;
+    readonly summary: string;
+    readonly repository: PluginRepository;
+    /** Registry-owned discovery categories; never used as installation authority. */
+    readonly categories?: readonly PluginCategory[] | undefined;
+    readonly categorySource?: PluginDiscoveryMetadataSource | undefined;
+    readonly kind?: PluginPackageKind | undefined;
+    readonly kindSource?: PluginDiscoveryMetadataSource | undefined;
+    readonly surfaces: {
+        readonly declared: readonly string[];
+        readonly verified: readonly string[];
+    };
+    readonly compatibility: PluginCompatibility;
+    readonly verification: PluginVerification;
+    readonly latestVersion?: PluginVersionSummary | undefined;
+    readonly license?: string | undefined;
+    readonly stars?: number | undefined;
+    readonly updatedAt?: string | undefined;
+}
+/** Search response with an opaque continuation cursor. */
+export interface PluginSearchPage {
+    readonly apiVersion: typeof PLUGIN_HUB_API_VERSION;
+    readonly catalogRevision: number;
+    readonly items: readonly PluginSummary[];
+    readonly nextCursor?: string | undefined;
+    readonly stale?: boolean | undefined;
+}
+/** Full read-only plugin description used by the Detail panel. */
+export interface PluginDetail extends PluginSummary {
+    readonly packagePath?: string | undefined;
+    readonly readme?: string | undefined;
+    readonly versions: readonly PluginVersionSummary[];
+    readonly os?: {
+        readonly declared: readonly string[];
+        readonly verified: readonly string[];
+    } | undefined;
+    readonly curation?: PluginCurationSummary | undefined;
+    readonly advisories?: readonly PluginAdvisorySummary[] | undefined;
+    readonly quarantined?: boolean | undefined;
+}
+/** Health of one profile-local third-party dependency. */
+export type InstalledPluginHealth = 'ok' | 'missing-package' | 'missing-entry' | 'manifest-invalid' | 'unknown';
+/** One dependency derived from the active profile rather than remote Catalog state. */
+export interface InstalledPlugin {
+    readonly packageName: string;
+    readonly version?: string | undefined;
+    readonly activeBundle: boolean;
+    readonly managed: boolean;
+    readonly pluginId?: PluginId | undefined;
+    readonly versionId?: PluginVersionId | undefined;
+    readonly sourceCommit?: string | undefined;
+    readonly artifactDigest?: string | undefined;
+    readonly health: InstalledPluginHealth;
+}
+/** Exact active-profile state used by installed and plan views. */
+export interface InstalledPluginSnapshot {
+    readonly profileRevision: string;
+    readonly bundles: readonly string[];
+    readonly plugins: readonly InstalledPlugin[];
+}
+/** Typed profile mutation represented by a detached plan. */
+export type PluginChangeOperation = 'install' | 'update' | 'remove';
+/** Descriptor facts shown before a user confirms an install or update. */
+export interface PluginChangeTarget {
+    readonly pluginId: PluginId;
+    readonly versionId: PluginVersionId;
+    readonly packageName: string;
+    readonly version: string;
+    readonly sourceCommit: string;
+    readonly artifactSizeBytes: number;
+    readonly artifactDigest: string;
+    readonly dshRange: string;
+    readonly validationLevel: string;
+    readonly lifecycleScripts: readonly string[];
+}
+/** Detached, expiring profile plan that contains no executable or local artifact path. */
+export interface PluginChangePlan {
+    readonly id: PluginChangePlanId;
+    readonly operation: PluginChangeOperation;
+    readonly profileRevision: string;
+    readonly createdAt: string;
+    readonly expiresAt: string;
+    readonly packageName: string;
+    readonly target?: PluginChangeTarget | undefined;
+    readonly before: InstalledPluginSnapshot;
+    readonly afterBundles: readonly string[];
+    readonly restartRequired: true;
+    readonly risks: readonly string[];
+}
+/** Successfully prepared staging generation awaiting explicit activation handoff. */
+export interface StagedPluginTransaction {
+    readonly id: PluginTransactionId;
+    readonly planId: PluginChangePlanId;
+    readonly operation: PluginChangeOperation;
+    readonly packageName: string;
+    readonly beforeRevision: string;
+    readonly afterRevision: string;
+    readonly createdAt: string;
+    readonly restartRequired: true;
+}
+/** Durable activation handoff that becomes owned by the maintenance process. */
+export interface PluginMaintenanceHandoff {
+    readonly transactionId: PluginTransactionId;
+    readonly state: 'waiting-for-old-process';
+    readonly createdAt: string;
+}
+/** Provider-neutral catalog implementation. */
+export interface PluginHubProvider {
+    readonly id: string;
+    /** Whether this provider may mutate and restart the active profile. */
+    readonly profileMutations: boolean;
+    status(signal?: AbortSignal): Promise<PluginHubStatus>;
+    search(request: PluginSearchRequest, signal?: AbortSignal): Promise<PluginSearchPage>;
+    plugin(pluginId: PluginId, signal?: AbortSignal): Promise<PluginDetail>;
+    installed(signal?: AbortSignal): Promise<InstalledPluginSnapshot>;
+    planInstall(pluginId: PluginId, versionId: PluginVersionId, signal?: AbortSignal): Promise<PluginChangePlan>;
+    planRemove(packageName: string, signal?: AbortSignal): Promise<PluginChangePlan>;
+    stage(planId: PluginChangePlanId, signal?: AbortSignal): Promise<StagedPluginTransaction>;
+    discard(transactionId: PluginTransactionId, signal?: AbortSignal): Promise<void>;
+    createMaintenanceHandoff(transactionId: PluginTransactionId, signal?: AbortSignal): Promise<PluginMaintenanceHandoff>;
+    markMaintenanceReady(signal?: AbortSignal): Promise<void>;
+}
+/** Safe in-process progress update; progress never enters a Session log. */
+export interface PluginHubProgress {
+    readonly operationId: string;
+    readonly phase: 'catalog' | 'download' | 'verify' | 'materialize' | 'mutate' | 'validate' | 'handoff';
+    readonly message: string;
+    readonly completed?: number;
+    readonly total?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@lingxi-ai-cn/dsh-plugin-hub",
+  "description": "Provider-neutral Plugin Hub catalog and profile transaction capability for native TUI consumers",
+  "version": "0.1.0-rc.8",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lingxi-AI-cn/dsh-tui-plugin.git",
+    "directory": "packages/interaction/plugin-hub"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-invariants": "0.1.0-rc.8",
+    "@deepseek-ai/cordis": "4.0.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-brand": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-invariants": "0.1.0-rc.8",
+    "@deepseek-ai/cordis": "4.0.1"
+  }
+}