@logictan/dsh-config-manager 0.1.60

package/lib/core/watcher.js

@@ -0,0 +1,219 @@
+/**
+ * 防抖文件监听 + 回声抑制（Phase 1 P0-1：自动快照）。
+ *
+ * 为什么把监听器做成 core 模块而不是直接在宿主里调 fs.watch：
+ *  1. **可测**：watch 工厂与定时器都由调用方注入，测试用假实现即可驱动时序，
+ *     不需要真文件系统、不依赖 sleep，避免既有的「负载相关偶发失败」类脆弱测试；
+ *  2. **回声抑制是一等公民**：恢复/回滚动作自己会写文件，若不抑制就会立刻产生
+ *     一个「等于刚写回内容」的自动快照，把重做通道堵死。本模块提供两层抑制：
+ *     `beginSuppress/endSuppress`（写操作窗口内直接丢弃事件）与 `EchoRegistry`
+ *     （窗口外按内容指纹识别回声，防「延迟投递的事件」漏网）。
+ *  3. **平台差异隔离**：Windows 上被监听目录删除/改名时 FSWatcher 会异步抛 EPERM，
+ *     不挂 error 处理器会变成未捕获 'error' 事件直接把进程炸掉——本模块统一接管。
+ */
+import path from 'node:path';
+const defaultTimers = {
+    setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
+    clearTimeout: (handle) => { globalThis.clearTimeout(handle); },
+};
+/** 临时文件 / 编辑器残留：默认忽略，避免「保存一次触发多轮快照」 */
+export function isIgnorableFileName(name) {
+    if (name === '')
+        return true;
+    if (name.startsWith('.'))
+        return true; // .git / .DS_Store / .swp 等
+    if (name.endsWith('~'))
+        return true; // 编辑器备份
+    if (name.endsWith('.tmp'))
+        return true; // 本仓库 atomicWriteFile 的中间产物
+    if (name.endsWith('.swp') || name.endsWith('.swo'))
+        return true;
+    if (/\.\d{6,}$/.test(name))
+        return true; // 版本化临时（file.json.1234567）
+    return false;
+}
+/**
+ * 防抖监听器：把高频文件事件合并成一次 `onFlush`。
+ *
+ * 生命周期：`start()` 建立监听；`stop()` 关闭全部监听并清掉待发定时器；
+ * `start()` 可在 `stop()` 后重新调用（幂等重建——宿主改配置后需要重建监听集）。
+ */
+export class DebouncedWatcher {
+    options;
+    timers;
+    handles = [];
+    timer = null;
+    pending = new Map();
+    suppressCount = 0;
+    running = false;
+    constructor(options) {
+        this.options = options;
+        this.timers = options.timers ?? defaultTimers;
+    }
+    get isRunning() {
+        return this.running;
+    }
+    /** 当前抑制深度（>0 表示正在执行会自写文件的操作） */
+    get suppressDepth() {
+        return this.suppressCount;
+    }
+    /** 待发事件数（测试与诊断用） */
+    get pendingCount() {
+        return this.pending.size;
+    }
+    start() {
+        this.stop();
+        this.running = true;
+        for (const dir of this.options.dirs) {
+            try {
+                const handle = this.options.watchFactory(dir, (_eventType, filename) => {
+                    this.onEvent(dir, filename);
+                });
+                this.handles.push({ dir, handle });
+            }
+            catch (error) {
+                this.options.onError?.(dir, error);
+            }
+        }
+    }
+    stop() {
+        for (const { handle } of this.handles) {
+            try {
+                handle.close();
+            }
+            catch {
+                // 关闭失败不影响其余清理
+            }
+        }
+        this.handles = [];
+        if (this.timer !== null) {
+            this.timers.clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.pending.clear();
+        this.running = false;
+    }
+    /**
+     * 进入抑制窗口：期间产生的文件事件**直接丢弃**。
+     * 调用方必须在 finally 里 `endSuppress()`，否则自动快照会永久停摆。
+     */
+    beginSuppress() {
+        this.suppressCount += 1;
+    }
+    /**
+     * 退出抑制窗口：深度归零时**顺带清空待发事件**——那些事件正是被抑制的写操作
+     * 自己产生的，若放行会立刻产生一个回声快照（挡住重做）。
+     */
+    endSuppress() {
+        if (this.suppressDepth === 0)
+            return;
+        this.suppressCount -= 1;
+        if (this.suppressDepth === 0) {
+            this.pending.clear();
+            if (this.timer !== null) {
+                this.timers.clearTimeout(this.timer);
+                this.timer = null;
+            }
+        }
+    }
+    /** 同步便捷包装：抑制窗口内执行 fn，异常也保证退出抑制。 */
+    suppressWhile(fn) {
+        this.beginSuppress();
+        try {
+            return fn();
+        }
+        finally {
+            this.endSuppress();
+        }
+    }
+    /** 异步便捷包装（恢复/回滚等长操作）。 */
+    async suppressWhileAsync(fn) {
+        this.beginSuppress();
+        try {
+            return await fn();
+        }
+        finally {
+            this.endSuppress();
+        }
+    }
+    onEvent(dir, filename) {
+        if (this.suppressDepth > 0)
+            return; // 抑制窗口：自写文件不触发快照
+        if (filename === null || typeof filename !== 'string')
+            return;
+        if (isIgnorableFileName(filename))
+            return;
+        const basename = path.basename(filename);
+        if (isIgnorableFileName(basename))
+            return;
+        // 同目录同文件去重（fs.watch 常对一次保存投递 change+rename 两个事件）
+        this.pending.set(`${dir}\u0000${filename}`, { dir, filename });
+        this.schedule();
+    }
+    schedule() {
+        if (this.timer !== null)
+            this.timers.clearTimeout(this.timer);
+        this.timer = this.timers.setTimeout(() => {
+            this.timer = null;
+            const events = [...this.pending.values()];
+            this.pending.clear();
+            if (events.length === 0)
+                return;
+            if (this.suppressDepth > 0)
+                return; // 定时器期间被抑制 → 丢弃
+            this.options.onFlush(events);
+        }, this.options.debounceMs);
+    }
+}
+/**
+ * 回声登记表：记录「我们刚刚写回的内容指纹」，用于识别监听器收到的
+ * 「恢复动作自己的写」这一回声。
+ *
+ * 与 `beginSuppress/endSuppress` 的分工：抑制窗口覆盖**写操作进行中**的事件；
+ * 本表覆盖**窗口之后才被投递**的延迟事件（macOS / 网络盘 / 杀毒软件扫描后
+ * 重写文件都可能造成事件晚到）。两条防线缺一不可——竞品的注释与 v0.4.6
+ * CHANGELOG 都记录了「macOS 延迟投递的回声快照挡住 redo」这一实际事故。
+ */
+export class EchoRegistry {
+    hashes = new Map();
+    /** 登记一次写回：key 建议 `${scope}:${relPath}`（如 `config:cordis.patch.yml`） */
+    record(key, hash) {
+        this.hashes.set(key, hash);
+    }
+    /** 是否仍等于我们写回的内容（= 回声，应忽略） */
+    isEcho(key, hash) {
+        return this.hashes.get(key) === hash;
+    }
+    has(key) {
+        return this.hashes.has(key);
+    }
+    get size() {
+        return this.hashes.size;
+    }
+    /**
+     * 清空。
+     * 语义：**真实变更一旦发生就清空整表**——否则后续对同一路径的合法修改
+     * 只要恰好等于某次历史写回内容就会被误判为回声而漏拍。
+     */
+    clear() {
+        this.hashes.clear();
+    }
+}
+/**
+ * 把事件批按「目录 → 文件名」聚合，便于调用方按关注目录分类。
+ * 返回 Map<dir, Set<filename>>（顺序无关，便于集合判定）。
+ */
+export function groupEventsByDir(events) {
+    const out = new Map();
+    for (const e of events) {
+        const set = out.get(e.dir) ?? new Set();
+        set.add(e.filename);
+        out.set(e.dir, set);
+    }
+    return out;
+}
+/** 事件批里是否包含关注的文件名（跨目录；用于「配置目录里出现了被关注的 basename」判定） */
+export function hasWatchedBasename(events, watched) {
+    return events.some((e) => watched.has(path.basename(e.filename)));
+}
+//# sourceMappingURL=watcher.js.map

package/lib/index.d.ts

@@ -0,0 +1,238 @@
+/**
+ * dsh-config-manager — host half.
+ *
+ * Mounts the backup / export / import engine (src/core Exporter + Importer
+ * three-stage flow) behind the `/api/dsh-config-manager/*` route family that
+ * the browser half (`./client`) calls, and wraps the real DSH host services
+ * into the engine's `HostContext` facade (src/core/types.ts):
+ *
+ *   ctx.settings           -> SettingsFacade      (@deepseek-ai/dsh-settings)
+ *   ctx.credentials        -> CredentialsFacade   (@deepseek-ai/dsh-credentials)
+ *   ctx.plugins            -> PluginsFacade       (官方 dsh plugin CLI 通道 + profile 文件，
+ *                                                  见 src/core/plugin-cli.ts)
+ *   ctx.workspaceRegistry  -> WorkspaceFacade     (@deepseek-ai/dsh-workspace)
+ *   ~/.dsh/cordis.patch.yml-> PatchFileFacade     (js-yaml)
+ *   $DSH_HOME files        -> FileSystemFacade    (node:fs, home-relative)
+ *   resolveDshHome()       -> homeDir             (@deepseek-ai/dsh-home-paths)
+ *
+ * Security posture (mirrors the verified @linxin666/dsh-ssh@0.1.12 routes):
+ *  - every route carries the loopback-only + same-origin trust fence
+ *    (isLoopbackRequest); LAN-exposed deployments never serve these endpoints;
+ *  - uploads/exported ZIPs are staged under $DSH_HOME/dsh-config-manager/{tmp,exports}
+ *    and every `path`/`zipPath` reference is confined to those roots;
+ *  - the encryption password is in-memory only: used to derive the AES-256-GCM
+ *    key for secrets.enc, never written to any file, manifest, or log;
+ *  - the import execute endpoint refuses to run without `confirm: true`
+ *    (core ImportNotConfirmedError safety valve).
+ *
+ * Optional services are read with ctx.get() at call time (never injected), so
+ * the engine keeps working in profiles without the web-only workspace
+ * service; hard dependencies are the core `settings`/`credentials` services
+ * present in every profile. Plugin install/list no longer depend on the
+ * web-only pluginMarketplace/pluginInventory services: both go through the
+ * official `dsh plugin --profile <name>` CLI (pnpm forwarder) and read the
+ * profile's package.json / node_modules directly.
+ */
+import type { ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+import type { CredentialProvider } from '@deepseek-ai/dsh-credentials';
+import { type RestorePlan, type RestoreReport } from './core/restore.ts';
+import type { MsgFunc } from './core/messages.ts';
+import { runDshPlugin } from './core/plugin-cli.ts';
+import type { PatchFileFacade, PluginInfo, PluginsFacade } from './core/types.ts';
+import type { SyncConfig } from './sync/sync-config.ts';
+import type { ConfiguredSecretPatterns } from './security/secret-scanner.ts';
+import type { SectionId } from './schema/types.ts';
+/** Stable cordis plugin name — must match the cordis.patch.yml row id. */
+export declare const name = "config-manager";
+/** Services required before the engine can mount (present in every profile). */
+export declare const inject: string[];
+/**
+ * 内置 GitHub OAuth App 的 client_id（「使用 GitHub 登录」device flow 缺省值）。
+ * Client ID 是公开标识（GitHub 官方明确非机密）：内置后所有安装者开箱即用，
+ * 无需各自注册/配置 OAuth App；token 仍按用户私有（各自授权、各自存 credentials）。
+ * 插件配置的 githubClientId 优先于本默认值（换自有 App 时覆盖）。
+ */
+export declare const DEFAULT_GITHUB_CLIENT_ID = "Ov23liq4i7n8UsylGRfb";
+/** Plugin config (composition entry); the loader applies it as-is. */
+export interface Config {
+    /** Master switch; defaults to true. */
+    enabled?: boolean;
+    /** Data root override; defaults to $DSH_HOME/dsh-config-manager. */
+    dataDir?: string;
+    /** 管理的 profile 名（插件依赖读写/安装目标）；缺省取启动参数 --profile，再缺省 'web'。 */
+    profile?: string;
+    /**
+     * GitHub OAuth App 的 client_id（「使用 GitHub 登录」device flow）。
+     * 缺省使用内置 DEFAULT_GITHUB_CLIENT_ID（公开标识，开箱即用）；
+     * 显式配置可覆盖（换自有 OAuth App 时）。
+     */
+    githubClientId?: string;
+    /**
+     * GitHub OAuth App 的 client_secret（confidential app 必需；public app 可省略）。
+     * 只存在于宿主进程：device flow 轮询时由宿主直接发送给 GitHub，绝不回传浏览器/日志。
+     */
+    githubClientSecret?: string;
+    /**
+     * pluginFiles 分区：额外白名单文件（相对 ~/.dsh 根的单文件名或子路径）。
+     * 与默认白名单（dsh-ssh.json、pet.json）合并；用于精确指定要随导出携带的插件配置文件。
+     */
+    pluginFiles?: string[];
+    /**
+     * pluginFiles 分区：约定的插件配置目录（相对 ~/.dsh 根，如 'plugin-config'）。
+     * 导出时递归收集该目录下所有文件（按相对 ~/.dsh 根的路径写回），实现「往目录放文件即自动随备份携带」。
+     */
+    pluginFilesDir?: string;
+    /**
+     * F2 个人隐私规则（对齐 dsh-packer config.personalPatterns）：个人化敏感字段名 /
+     * 引用字段 / 值形状模式，由部署者注入（个人昵称、本机用户名等），不进开源代码。
+     * 未配置时扫描器行为与默认完全一致。
+     */
+    personalPatterns?: ConfiguredSecretPatterns;
+}
+/**
+ * 同步 token 的 DSH credentials 引用名（POSIX env-var 形态，满足 CredentialRef 品牌要求）。
+ * token 只经 credentialRef 读写（写入由请求体触发，读取在每次 git 网络操作时 resolve），
+ * 永不进 repoUrl / argv / commit / 同步文件 / 日志。
+ */
+export declare const SYNC_CREDENTIAL_REF = "DSH_CONFIG_MANAGER_SYNC_TOKEN";
+/**
+ * WebDAV 通道口令的独立 DSH credentials 引用（与 git token 槽位分离）。
+ * 口令只经 credentialRef 读写（写入由请求体触发，读取在每次 WebDAV 网络操作时
+ * by WebDavTransport 经注入的 getPassword() resolve），永不进 URL / 请求头 / 日志。
+ */
+export declare const SYNC_WEBDAV_CREDENTIAL_REF = "DSH_CONFIG_MANAGER_SYNC_WEBDAV_PASSWORD";
+/** 包名 → patch 行 id slug（仿 marketplace ensureRow）：去 @、非法字符→-、连续-合并、去首尾-。 */
+export declare function slugOf(name: string): string;
+/** 某 patch 行（raw）是否激活了指定包名（兼容单行与 insert 块成员）。 */
+export declare function patchRowActivates(raw: unknown, name: string): boolean;
+/**
+ * 非 bundle 插件安装成功后，幂等补 profile cordis.patch.yml 激活行
+ * （{id: pm-<slug>, name: <pkg>}，仿 marketplace ensureRow）。bundle 包不写行
+ * （CLI 的 reconcile 已维护 dsh.profile.bundles）。
+ */
+export declare function ensureActivationRow(patchFile: PatchFileFacade, pkgDir: string, pkg: string): Promise<void>;
+/**
+ * Plugins facade：官方 dsh plugin CLI 通道（任何 profile 可用）+ profile 文件
+ * 实时清单 + 非 bundle 插件激活行幂等补写。不再依赖 web 专用
+ * pluginMarketplace / pluginInventory 服务。
+ *
+ * 导出 + runner 可注入：M5 单测用 mock runner 验证「无 marketplace 时 install
+ * 走 CLI 通道」的行为契约，不触发真实子进程；生产路径默认参数不变。
+ */
+export declare class DshPluginsFacade implements PluginsFacade {
+    private readonly homeDir;
+    private readonly profile;
+    private readonly patchFile;
+    private readonly msg;
+    private readonly runner;
+    constructor(homeDir: string, profile: string, patchFile: PatchFileFacade, runner?: typeof runDshPlugin, msg?: MsgFunc);
+    listInstalled(): Promise<PluginInfo[]>;
+    install(pkg: string, spec?: string, signal?: AbortSignal): Promise<{
+        needsRestart: boolean;
+    }>;
+}
+/** 同步路由可预期的请求级错误（status 缺省 400；引擎/传输失败走 500） */
+export declare class SyncRouteError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+/** 同步路由错误统一出口：SyncRouteError 用其 status，其余 500（GitTransport 错误消息已脱敏） */
+export declare function writeSyncRouteError(res: ServerResponse, error: unknown): void;
+/** parseSyncBody 的凭据写入依赖（只用到 set；测试可注入内存 mock）。 */
+export interface ParseSyncBodyDeps {
+    credentials: Pick<CredentialProvider, 'set'>;
+}
+/**
+ * 解析同步请求体，按 transport 分支返回归一化的 SyncConfig（可辨识联合，schemaVersion=2）。
+ * 请求体形状（flat，M4 契约）：
+ * - git:    { transport:'git', repoUrl, token? } —— token 非空写 SYNC_CREDENTIAL_REF；
+ *   git 可执行文件固定使用系统 PATH 中的 git（不再接受自定义 gitBin）。
+ * - webdav: { transport:'webdav', url, username?, password? } —— password 非空写 SYNC_WEBDAV_CREDENTIAL_REF。
+ * 返回值不含任何 secret（password/token 只进 credentials，永不回传/落同步文件）。
+ */
+export declare function parseSyncBody(body: Record<string, unknown>, deps: ParseSyncBodyDeps): Promise<SyncConfig>;
+/** 由 SyncConfig 合成 WebDAV 通道 baseUrl（webdav.url，尾部规范化带 '/'；git 通道返回 ''）。 */
+export declare function webdavBaseUrl(cfg: SyncConfig): string;
+/**
+ * 补全 webdav 配置缺失的 username（从持久化配置回填；纯函数，不修改入参）。
+ * 语义与 password 一致：请求未带 username（表单留空/挂载自动加载）→ 沿用已保存的值；
+ * 请求显式带 username → 原样保留（用户新输入优先）。非 webdav / 无持久化 → 原样返回。
+ */
+export declare function mergePersistedWebDavUsername(cfg: SyncConfig, persisted: SyncConfig | null): SyncConfig;
+/**
+ * 解析 push 请求体的分区选择（sections）——「高级/自定义导出」模式负载。
+ * - 缺省 / 非数组 / 空数组 → undefined（= 全部 portable 推荐分区，即「默认/快速导出」模式）；
+ * - 元素必须是 knownIds（已知 adapter id）中的非空字符串，非法 → SyncRouteError（不静默吞错）；
+ * - 返回去重后的数组（保持原顺序；重复分区不做重复导出）。
+ */
+export declare function extractSyncSections(body: Record<string, unknown>, knownIds: ReadonlySet<string>): SectionId[] | undefined;
+/** POST /restore 请求体校验（纯函数；snapshotId 拒绝路径分隔符防 join 越界）。 */
+export type BuildRestoreBodyResult = {
+    ok: true;
+    value: {
+        snapshotId: string;
+        dryRun: boolean;
+    };
+} | {
+    ok: false;
+    error: string;
+};
+export declare function buildRestoreBody(body: unknown): BuildRestoreBodyResult;
+/**
+ * 宿主侧恢复动作执行器（真实执行 restore 计划）：
+ * 整文件/文件还原与删除走 ctx.fs（home-relative facade，越界由 facade 再拦一道），
+ * blob 读取与 pre-restore 副本走快照目录（node fs），插件卸载走官方 dsh plugin CLI。
+ */
+export interface RestoreExecutor {
+    /** 读快照目录内 blob（相对 snapshotDir） */
+    readBlob(blobPath: string): Promise<Uint8Array>;
+    /** 把当前 home 文件内容复制到 <snapshotDir>/pre-restore/（覆盖/删除前的双保险） */
+    savePreRestore(relPath: string): Promise<void>;
+    existsHome(relPath: string): Promise<boolean>;
+    writeHome(relPath: string, data: Uint8Array): Promise<void>;
+    removeHome(relPath: string): Promise<void>;
+    /** 卸载插件（官方通道）；失败返回 { ok:false, message } */
+    uninstallPlugin(name: string): Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+}
+/**
+ * 按计划执行恢复动作（纯执行器；逐项 try/catch 不拖垮其余），
+ * 返回与 CLI 一致的诚实报告。顺序 = 计划顺序（整文件 → 插件 → file 补偿）。
+ * @param onAction - 每项动作执行回调（宿主路由埋点：更新 RunRegistry 进度；
+ *   index/1-based、total=计划动作数、detail=动作描述）
+ */
+export declare function executeRestorePlan(plan: RestorePlan, exec: RestoreExecutor, onAction?: (info: {
+    index: number;
+    total: number;
+    detail: string;
+}) => void): Promise<RestoreReport>;
+/**
+ * GitHub 凭据「缺失或失效」判定（issue #29）：`no_token`（credentials 里从未配置 token）与
+ * `unauthorized`（401，token 过期/被撤销）对用户都是同一个「未登录」，必须走同一分支——
+ * 否则 `no_token` 会落到 500，UI 把「未登录」渲染成「登录状态读取失败」的误导性横幅。
+ * 其余分类（network_error / rate_limited / server_error / validation_failed / fork_timeout…）
+ * 是真实故障，仍按 500 暴露，绝不伪装成「未登录」。
+ */
+export declare function isGitHubAuthMissing(error: unknown): boolean;
+/** /status 的插件诊断位（issue #28）。仅回非敏感元信息：目录、profile 名、计数。 */
+export interface PluginDiagnostics {
+    homeDir: string;
+    profile: string;
+    /** profile 目录的 package.json 是否可读（不可读 → 清单必然为空） */
+    profileManifestReadable: boolean;
+    /** 插件清单来源 = package.json 的 dependencies 里非 in-box 的包 */
+    installedPluginCount: number;
+    installedPluginNames: string[];
+    /** dsh.profile.bundles 声明（非空即「替换默认插件栈」） */
+    bundles: string[];
+}
+/**
+ * Mount the config-manager engine: host context, adapters, and the
+ * /api/dsh-config-manager routes (when a webServer is present).
+ * @param ctx - host plugin context carrying settings/credentials/webServer.
+ * @param config - resolved plugin config.
+ */
+export declare function apply(ctx: Context, config?: Config): void;