dsh-plugin-manager-companion 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * dsh-plugin-manager-companion — 插件入口与 op 分派。
+ *
+ * 归属：A 类·重写（旧仓库入口 2358 行，把服务、路由、job、缓存闭包全塞在一起）。
+ * 官方复用：ctx.profileContext / ctx.pluginManager（经 official.ts 探测）/ ctx.settings /
+ *   ctx.webServer / ctx.tools / ctx.systemPrompt。
+ * 前提检查：旧仓库入口自建 27 个 REST op + job 系统 + patch 写入，前提是"官方只有只读清单"。
+ *   0.1.6 之后前提消失：**当前环境**的写操作全部交还官方 Remote；本入口只保留官方不覆盖的部分
+ *   （深度诊断、跨环境管理、市场、技能与预设、质量门编排）。
+ *
+ * 硬约束：服务名绝不用 pluginManager（官方已占用，同名会让整个 profile 起不来）。
+ */
+import type { Context } from "@deepseek-ai/cordis";
+import type { TrialInstallOptions, TrialInstallResult } from "./envManager.ts";
+import { type OfficialCapabilities } from "./official.ts";
+import { type UpgradeEngineDeps } from "./upgrade.ts";
+import { JobRegistry, type Envelope } from "./rest.ts";
+import { type CompanionConfig, type ConfigHandle } from "./settings.ts";
+import type { GatedInstallResult } from "./types.ts";
+/** 本插件对外的服务名。绝不用 pluginManager —— 那是官方的。 */
+export declare const SERVICE_NAME = "companion";
+/** 插件配置的 schema，供宿主配置界面与校验使用。 */
+export { ConfigSchema } from "./settings.ts";
+/** Loader 行名，等于包名；cordis.patch.yml 必须用同一个 id。 */
+export declare const name = "dsh-plugin-manager-companion";
+/** 装配时必需的服务；官方能力用 get 探测，因此这里只列真正硬需要的。 */
+export declare const inject: string[];
+/** 一次装配持有的运行时状态。 */
+interface CompanionRuntime {
+    readonly capabilities: OfficialCapabilities;
+    readonly config: ConfigHandle;
+    readonly jobs: JobRegistry;
+}
+/** 读取当前装配状态（诊断与 UI 用）。未装配时返回 undefined。 */
+export declare function currentRuntime(): CompanionRuntime | undefined;
+/**
+ * 试装执行器（测试注入替身）。
+ *
+ * 为什么要留这个缝：试装会真起进程（headless 验证）。单测要证明的是"接进来了、策略生效了"，
+ * 不能靠真的起一个 dsh 来证明——那是真机 e2e 的活。
+ */
+export type TrialRunner = (spec: string, realName: string, options: TrialInstallOptions) => Promise<TrialInstallResult>;
+/** gatedInstall 的可选注入。 */
+export interface GatedInstallOptions {
+    /** 试装执行器；省略时用真实的 runTrialInstall（会真装、真起进程）。 */
+    readonly trial?: TrialRunner;
+}
+/**
+ * 受质量门保护的安装。
+ *
+ * 三步走，全部经官方通道，零竞态：
+ *   1. inspect(spec) —— 官方读 spec 指向什么（拒绝非法/已装/非 bundle）
+ *   2. installBundle(spec, { enabled: false }) —— 官方装但**不激活**
+ *   3. 扫描已安装包（我们的质量门）
+ *       合格 → setBundleEnabled(name, true) 激活
+ *       不合格 → removeBundle(name) 回滚
+ *
+ * 为什么不需要"安装前钩子"：官方提供了 enabled:false 这个开关（官方 UI 自己就用它）。
+ * 装上但不激活，等于把包放进隔离区，扫完再决定是否放行——比"先扫后装"更可靠，
+ * 因为扫描对象真实存在于目标位置。
+ *
+ * 试装（第二步，DESIGN §5.2）接在**静态快筛之后、真正放行之前**：一条路径，Web UI /
+ * CLI / agent 工具三边同时生效。试装关闭时（默认）本函数的行为与没有它时逐条相同。
+ *
+ * 两处刻意的实现细节：
+ *   · 质量门**整体**关闭或包在豁免名单里时，试装不执行——但会在输出里写明"试装未执行"，
+ *     不让"我打开了开关却什么都没发生"变成一个看不见的洞。
+ *   · 试装没通过时的处置由设置决定（默认不装），但**无论哪一档**，"无法试装"都不会被写成通过。
+ *
+ * @param ctx - host 上下文。
+ * @param config - 本插件配置。
+ * @param spec - 安装 spec（npm 名 / git 地址 / 本地路径 / tarball）。
+ * @param environmentName - 目标环境名；undefined 表示当前环境。
+ * @param options - 可选注入（试装执行器）。
+ * @returns 结果；失败时输出里说明是官方拒绝、质量门拦截、试装未通过还是激活失败。
+ */
+export declare function gatedInstall(ctx: Context, config: CompanionConfig, spec: string, environmentName?: string, options?: GatedInstallOptions): Promise<GatedInstallResult>;
+/** op 分派需要的外部依赖（测试可注入替身）。 */
+export interface OpDependencies {
+    readonly ctx: Context;
+    readonly config: () => CompanionConfig;
+    readonly configUpdate: (patch: Partial<CompanionConfig>) => Promise<CompanionConfig>;
+    readonly capabilities: () => OfficialCapabilities;
+    readonly jobs: JobRegistry;
+    /** 试装执行器；省略时用真实的 runTrialInstall（会真装候选包并起进程）。 */
+    readonly trial?: TrialRunner;
+    /** 升级引擎依赖（ctx / 官方运行器 / 试装执行器 / 抓取器 的注入缝）。 */
+    readonly upgrade?: UpgradeEngineDeps;
+}
+/**
+ * 执行一个 op。
+ *
+ * 分派表刻意扁平：每个 op 一行到几行，复杂编排下沉到各模块（gatedInstall 是唯一例外，
+ * 因为它跨官方 Remote 与我们的质量门，属于入口职责）。
+ *
+ * @param op - 操作名。
+ * @param body - 请求体。
+ * @param deps - 依赖。
+ * @returns 响应信封。
+ */
+export declare function handleOp(op: string, body: Record<string, unknown>, deps: OpDependencies): Promise<Envelope<unknown>>;
+/**
+ * 注册自有 REST 路由。
+ *
+ * 官方能力（插件启停/安装/卸载/清单）**不在这里**——客户端直连官方 Remote。
+ * 这里只暴露官方不覆盖的部分：诊断、环境管理、市场、技能与预设、配置。
+ *
+ * @param ctx - host 上下文。
+ * @param deps - op 分派依赖。
+ * @returns 路由 disposer 列表。
+ */
+export declare function registerRoutes(ctx: Context, deps: OpDependencies): (() => void)[];
+/**
+ * 插件装配。
+ *
+ * 只做"必须有"的事：注册配置命名空间、探测官方能力、装 REST 路由与 agent 工具。
+ * 各能力模块在各自的调用点被用到，不做无意义的预先初始化（诊断与市场都是按需触发）。
+ *
+ * @param ctx - host 上下文。
+ */
+export declare function apply(ctx: Context): void;