dsh-plugin-manager-companion 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * dshpmc —— dsh-plugin-manager-companion 的命令行入口。
+ *
+ * 归属：A 类·重写（可执行入口；旧 src/cli.ts 仅作意图参考，未复制代码）。
+ * 旧实现参考：dsh-web-plugin-manager/src/cli.ts（400 行：bin 名 dshpm、命令集合
+ *   install/remove/update/mount/list/analyze/uninstall-kind、全局 flag
+ *   --profile/--home/--env、ctx 可空时跳过 live 应用、git 源缺 env 时给出
+ *   续装命令）。
+ * 官方复用：**包操作全部走官方 @deepseek-ai/dsh-plugin-manager/operations 的
+ *   runPluginCommand**——它自带 profile 写锁（withFileLock）、profile 初始化、
+ *   输出落盘与 bundle 激活，与 dsh plugin 命令、官方 plugin_manager 工具是同一条
+ *   pnpm 通道。安装锚点优先取官方 @deepseek-ai/dsh/profile-boot 的 INSTALL_ANCHOR。
+ *   本文件不拼任何 pnpm 参数、不写 package.json、不碰 cordis.patch.yml。
+ * 前提检查：旧实现的前提（必须在 profile 里跑 pnpm、必须自己维护 insert 行）已消失：
+ *   0.1.6 的官方 operations 按 profile 参数化，所以"管理另一个环境"= 换一个
+ *   profile 参数，不是自建第二条写路径。旧实现的 mount（自己往 patch 里写挂载行）
+ *   被**删除**：官方 plugin_manager 的 set_plugin/set_bundle 才是挂载与启停的唯一
+ *   入口，这里只做只读盘点并把正确动作报给用户。
+ *
+ * 退出码：0 成功；1 发现问题（analyze）/ 操作失败；2 用法或环境错误。
+ * bin 名刻意用 dshpmc（旧包用 dshpm），两个包共存期间不会互相抢 bin。
+ */
+import { type CompanionConfig } from './settings.ts';
+import type { DiagnosticReport, EnvironmentInfo } from './types.ts';
+/** 官方 runPluginCommand 的入参形状（结构式，见下）。 */
+export interface PluginOperationContext {
+    readonly profile: string;
+    /** 显式环境目录；省略时官方自己解析。 */
+    readonly dir?: string;
+    /** dsh 自身安装的 package.json 绝对路径。 */
+    readonly installAnchor: string;
+    /** 调用方的工作目录（相对路径安装源按它解析）。 */
+    readonly cwd: string;
+    /** Harness home。 */
+    readonly home?: string;
+}
+/** 官方包操作的执行策略。 */
+export interface PluginOperationOptions {
+    readonly execution: 'cli' | 'service';
+    readonly outputBytes: number;
+    readonly lockWaitMs?: number;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly onOutput?: (text: string, stream: 'stdout' | 'stderr') => void;
+}
+/** 官方包操作的返回。 */
+export interface PluginOperationResult {
+    readonly exitCode: number | null;
+    readonly output: string;
+    /** 失败分类（官方 classifyInstallFailure 的结果），可能缺省。 */
+    readonly kind?: string;
+    /** 官方写下的完整日志路径。 */
+    readonly logPath?: string;
+}
+/** 与官方 operations 对接的那一个函数。 */
+export type RunPluginCommand = (context: PluginOperationContext, args: readonly string[], options: PluginOperationOptions) => Promise<PluginOperationResult>;
+/** CLI 的可注入依赖（测试用来替代真实 pnpm 与诊断引擎）。 */
+export interface CliDependencies {
+    /** 跑一次修复动作；由宿主注入（CLI 不 import 诊断引擎，见文件头说明）。 */
+    readonly analyze?: (environmentName: string, config: CompanionConfig) => Promise<DiagnosticReport>;
+    /** 官方 runPluginCommand；缺省时 CLI 会动态 import 官方包，两条路都不通就报错。 */
+    readonly runPluginCommand?: RunPluginCommand;
+    /** 安装锚点覆盖（宿主进程里应传 ctx.profileContext.installAnchor）。 */
+    readonly installAnchor?: string;
+    /** 标准输出。 */
+    readonly stdout?: (text: string) => void;
+    /** 标准错误。 */
+    readonly stderr?: (text: string) => void;
+}
+/** 解析后的全局 flag。 */
+export interface CliOptions {
+    readonly command: string;
+    /** 位置参数（命令之后的非 flag 词）。 */
+    readonly args: readonly string[];
+    readonly profile: string;
+    /** --home 覆盖；未给时 undefined。 */
+    readonly home?: string;
+    /** --env KEY=value。 */
+    readonly env: Readonly<Record<string, string>>;
+    readonly json: boolean;
+    /** 少数命令的支持项：marketplace 强制刷新等；也用于跳过确认类动作。 */
+    readonly flags: ReadonlySet<string>;
+}
+/** 默认 profile（与旧实现一致：web 是绝大多数用户的环境）。 */
+export declare const DEFAULT_PROFILE = "web";
+/** 用法文本。 */
+export declare const USAGE: string;
+/**
+ * 解析 argv。
+ *
+ * 全局 flag 可以出现在命令前或命令后（与官方 CLI 的解析器一致），因此解析一遍
+ * 就够，不需要位置状态机。未知 flag 也接受：CLI 是给工具与其他脚本调的，
+ * 对未知 flag 报错只会让上游版本升级变脆。
+ *
+ * @param argv - 进程参数（不含 node 与脚本路径），也可以用完整 process.argv。
+ * @returns 解析结果。
+ * @throws 缺少命令名或 --env 形式非法时。
+ */
+export declare function parseArgs(argv: readonly string[]): CliOptions;
+/**
+ * 解析官方 dsh 安装的 package.json 锚点。
+ *
+ * 三条路，按可靠性排序：
+ *   1. 注入（宿主进程里应传 ctx.profileContext.installAnchor）；
+ *   2. 官方 @deepseek-ai/dsh/profile-boot 的 INSTALL_ANCHOR（CLI 跑在装了 dsh 的
+ *      profile 里时可用）；
+ *   3. 从 CLI 自身位置向上找 node_modules/@deepseek-ai/dsh/package.json。
+ * 三条都不通时**不猜**：返回 undefined，由调用方给出可执行的报错。
+ *
+ * @param injected - 注入的锚点。
+ * @returns 锚点绝对路径；解析不出时 undefined。
+ */
+export declare function resolveInstallAnchor(injected?: string): Promise<string | undefined>;
+/**
+ * 取官方 runPluginCommand；注入优先，否则动态 import。
+ *
+ * 动态 import 而不是静态 import 的原因是构建顺序：静态 import 会让本文件的编译
+ * 依赖官方子路径的解析结果，而 CLI 可能在官方包不可用的环境里构建/使用。
+ * 解析失败不是一个崩溃点，而是一个可读的操作错误。
+ *
+ * @param injected - 注入的实现。
+ * @returns 官方实现。
+ * @throws 官方包不可解析时。
+ */
+export declare function loadRunPluginCommand(injected?: RunPluginCommand): Promise<RunPluginCommand>;
+/** 引擎模块的最小结构式视图：动态加载，加载失败也要能报出可读原因。 */
+interface AnalyzerModule {
+    analyzeEnvironment(ctx: unknown, env: Record<string, unknown>, config: CompanionConfig): Promise<DiagnosticReport>;
+}
+/** 诊断目标：EnvironmentInfo 加上可选安装锚点（与 diagnostics.ts 的 DiagnosticTargetEnvironment 同形）。 */
+type AnalyzeTarget = EnvironmentInfo & {
+    readonly installAnchor?: string;
+};
+/**
+ * 最小 host 上下文。
+ *
+ * 引擎对 ctx 只做两件事：ctx.get('profileContext') 取安装锚点、ctx.logger 记账。
+ * CLI 进程里两样都没有：get 一律 undefined（引擎会把它记成"没有锚点"的 skipped，
+ * 而不是当成"包不存在"），logger 用空实现。**不假装自己是宿主**。
+ *
+ * @returns 结构式最小上下文。
+ */
+export declare function minimalCliContext(): {
+    get(name: string): undefined;
+    logger: Record<string, () => void>;
+};
+/**
+ * 动态加载诊断引擎。
+ *
+ * 刻意不用静态 import：CLI 要在引擎的官方依赖（app-boot / plugin-inventory 等）缺失时
+ * 也能报出**可读的原因**，而不是让整个 bin 加载失败。说明符放在变量里，避免打包/编译期
+ * 去解析一个不保证存在的模块。
+ *
+ * @returns 引擎模块或失败原因。
+ */
+export declare function loadAnalyzer(): Promise<{
+    readonly analyzer?: AnalyzerModule;
+    readonly reason?: string;
+}>;
+/**
+ * 由磁盘事实构造诊断目标（不依赖宿主）。
+ *
+ * @param name - 环境名。
+ * @param installAnchor - 已解析的安装锚点；解析不出时不传（引擎会如实记 skipped）。
+ * @returns 诊断目标。
+ */
+export declare function environmentTargetFor(name: string, installAnchor?: string): AnalyzeTarget;
+/**
+ * 启动阶段硬失败的根因特征。
+ *
+ * 这三种"脏"会让 dsh 在启动阶段就退出：用户连界面都没有，诊断页也永远看不到。
+ * CLI 是唯一的逃生口，所以这里把根因文本显式挑出来单独展示——即便它在报告里的
+ * 身份只是"某层被跳过的原因"（官方 composeEntries / loadProfileDirectory 会抛错，
+ * 引擎把抛错原因记进 skipped）。
+ */
+export declare const BOOT_BLOCKER_SIGNATURES: readonly string[];
+/**
+ * 关键核对项：这些没跑完，就不能说"环境没问题"。
+ *
+ * 与"结构性不可用"分开：CLI 里没有活 Loader，运行时层（runtime）永远跳过，那是**已知且预期**
+ * 的缺失（要显著告知，但不构成"有问题"）；而依赖/组合/一致性三层是只读磁盘就能跑的，
+ * 它们跳过说明这次诊断并没有真正覆盖到"环境能不能起来"。
+ */
+export declare const CRITICAL_SKIP_CHECKS: readonly string[];
+/** 一次诊断的完整判定：覆盖情况 + 根因 + 退出码语义。 */
+export interface AnalyzeCoverage {
+    /** 哪个层跑完了 / 跳过了 / 被配置关闭。 */
+    readonly layers: readonly {
+        readonly layer: string;
+        readonly state: 'ran' | 'skipped' | 'disabled';
+    }[];
+    /** 关键核对项没完成的原因（人类可读）。 */
+    readonly incomplete: readonly string[];
+    /** 启动阶段硬失败的根因文本（可能来自 skipped.reason，而不只是 issues）。 */
+    readonly blockers: readonly string[];
+    /** 判定：发现问题 / 没跑完 / 干净。 */
+    readonly verdict: 'issues' | 'incomplete' | 'clean';
+    /** 退出码：0 干净；1 有问题或没跑完；2 用法/环境错误由调用方给。 */
+    readonly code: number;
+}
+/**
+ * 判定一次诊断的结果与退出码。
+ *
+ * 语义（刻意不让 issues=0 等于"健康"）：
+ *   - 有问题 → 'issues' / 1；
+ *   - 没问题但**关键核对项没跑完**（组合层读不出来、缺安装锚点）→ 'incomplete' / 1，
+ *     由调用方在文案里说清楚"这次没能完成组合层核对"；
+ *   - 只有关键项都跑完且没问题才是 'clean' / 0。
+ *
+ * @param report - 引擎报告。
+ * @param notes - 调用方补充的事实（例如"没有安装锚点"）。
+ * @returns 判定结果。
+ */
+export declare function judgeAnalyze(report: DiagnosticReport, notes?: {
+    readonly anchorMissing?: boolean;
+    readonly disabledLayers?: readonly string[];
+}): AnalyzeCoverage;
+/**
+ * CLI 主入口。
+ *
+ * @param argv - 参数（不含 node 与脚本路径；传 process.argv.slice(2)）。
+ * @param deps - 可注入依赖（测试/宿主用）。
+ * @returns 退出码。
+ */
+export declare function main(argv: readonly string[], deps?: CliDependencies): Promise<number>;
+export {};