dsh-config-manager 0.1.0

package/lib/core/rollback.js

@@ -0,0 +1,136 @@
+/**
+ * Rollback（规范 §17 / 设计 §8.2）：导入失败时逆序执行快照条目的补偿动作。
+ *
+ * 诚实原则：
+ *  - 尽力回滚：单项失败不停止其余补偿，最终如实报告 full / partial；
+ *  - credential 值 DSH 永不回读 → existed=true 的凭据无法自动恢复原值，
+ *    如实标记 failed + manualHint（人工补录）；
+ *  - settings 回滚仍走 expectedRevision 乐观锁，避免覆盖导入后用户的新修改。
+ */
+import { resolveFileTarget } from "./backup.js";
+/** 逆序补偿单条快照条目；返回 null=成功，否则为失败原因 */
+async function compensateOne(entry, ctx, store) {
+    switch (entry.kind) {
+        case 'settingsNamespace': {
+            try {
+                if (!entry.existed) {
+                    // 原目标不存在该 namespace：若导入已创建它，DSH settings 无删除语义 → 无法恢复「不存在」
+                    let current = null;
+                    try {
+                        current = await ctx.settings.describe(entry.ref);
+                    }
+                    catch {
+                        current = null;
+                    }
+                    if (current === null)
+                        return null; // 本来就没有且未创建 → 无需恢复
+                    return {
+                        reason: '该 namespace 由导入创建，DSH settings 无删除语义',
+                        manualHint: `namespace "${entry.ref}" 需人工删除或合并`,
+                    };
+                }
+                // 用当前 revision 作乐观锁基准：读时即锁，冲突则如实失败（不覆盖并发修改）
+                const current = await ctx.settings.describe(entry.ref);
+                await ctx.settings.replace(entry.ref, entry.before, current.revision);
+                return null;
+            }
+            catch (err) {
+                return { reason: err instanceof Error ? err.message : String(err), manualHint: `settings namespace "${entry.ref}" 需人工核对` };
+            }
+        }
+        case 'credential': {
+            if (entry.existed) {
+                // 值不可回读：无法自动恢复原值
+                return {
+                    reason: 'DSH 不回读凭据值，无法自动恢复',
+                    manualHint: `凭据 "${entry.ref}" 请人工重新填写`,
+                };
+            }
+            try {
+                await ctx.credentials.unset(entry.ref);
+                return null;
+            }
+            catch (err) {
+                return { reason: err instanceof Error ? err.message : String(err) };
+            }
+        }
+        case 'patchLine': {
+            try {
+                const file = entry.ref.split('\u0000')[0] ?? 'cordis.patch.yml';
+                const lineId = entry.ref.includes('\u0000') ? entry.ref.split('\u0000')[1] : entry.ref;
+                await ctx.patchFile.applyPatchChanges(file, [
+                    { lineId, raw: entry.before, action: entry.before === null ? 'remove' : 'update' },
+                ]);
+                return null;
+            }
+            catch (err) {
+                return { reason: err instanceof Error ? err.message : String(err), manualHint: `patch 行 "${entry.ref}" 需人工核对` };
+            }
+        }
+        case 'file': {
+            try {
+                const abs = resolveFileTarget(ctx, entry.adapter, entry.ref);
+                if (entry.existed && entry.copiedTo && store) {
+                    const data = await store.readBlob(entry.snapshotId ?? '', entry.copiedTo);
+                    await ctx.fs.writeFile(abs, data);
+                }
+                else if (!entry.existed) {
+                    // 原文件不存在 → 删除导入写入的文件
+                    if (await ctx.fs.exists(abs))
+                        await ctx.fs.remove(abs);
+                }
+                return null;
+            }
+            catch (err) {
+                return { reason: err instanceof Error ? err.message : String(err), manualHint: `文件 "${entry.ref}" 需人工恢复` };
+            }
+        }
+        case 'workspaceRecord': {
+            try {
+                if (entry.before === null) {
+                    await ctx.workspace.removeRecord?.(entry.ref);
+                }
+                else {
+                    await ctx.workspace.writeRecord(entry.before);
+                }
+                return null;
+            }
+            catch (err) {
+                return { reason: err instanceof Error ? err.message : String(err), manualHint: `workspace "${entry.ref}" 需人工核对` };
+            }
+        }
+        default:
+            return { reason: `未知快照条目类型 ${entry.kind}` };
+    }
+}
+/** 回滚：逆序补偿全部条目；返回诚实报告（full / partial） */
+export async function rollback(opts) {
+    const { ctx, snapshot, store, adapters } = opts;
+    const restored = [];
+    const failed = [];
+    // 逆序遍历；adapter 自带的 rollback? 优先，否则引擎通用补偿
+    const entries = [...snapshot.entries].reverse();
+    for (const entry of entries) {
+        const adapter = adapters?.find((a) => a.id === entry.adapter);
+        let error = null;
+        if (adapter?.rollback) {
+            try {
+                await adapter.rollback([entry], ctx);
+            }
+            catch (err) {
+                error = { reason: err instanceof Error ? err.message : String(err) };
+            }
+        }
+        else {
+            error = await compensateOne(entry, ctx, store);
+        }
+        if (error === null) {
+            restored.push(`${entry.adapter}:${entry.ref}`);
+        }
+        else {
+            failed.push({ item: `${entry.adapter}:${entry.ref}`, reason: error.reason, manualHint: error.manualHint });
+        }
+    }
+    return { full: failed.length === 0, restored, failed };
+}
+//# sourceMappingURL=rollback.js.map

package/lib/core/rollback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback.js","sourceRoot":"","sources":["../../src/core/rollback.ts"],"names":[],"mappings":"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"}

package/lib/core/types.d.ts

@@ -0,0 +1,331 @@
+/**
+ * 核心引擎契约类型（对齐 Docs/design/architecture.md §13.2/§13.3/§13.5）。
+ *
+ * 关键解耦原则：核心引擎只依赖这里的接口，绝不 import DSH 运行时包。
+ * HostContext 是 m3 定义、m5 实现的 DSH Service 门面（研究报告 §3.2 的叶子方法最小集），
+ * 测试用内存 mock 即可驱动完整导出→导入往返。
+ */
+import type { EncryptionInfo, Manifest, SectionId, WorkspaceRecord } from '../schema/types.ts';
+import type { Logger } from '../utils/logger.ts';
+export interface ExportOptions {
+    /** 是否包含真实秘密（必须配合 encryption 提供者；缺省 false = 只导状态） */
+    includeSecrets: boolean;
+    /** 仅导出指定分区（缺省 = 全部默认包含分区） */
+    only?: SectionId[];
+    /** 导出文件路径（缺省自动生成 dsh-config-<date>.zip） */
+    outPath?: string;
+}
+/** adapter.export() 的产出：数据 + 文件 + 报告计数 + 告警 */
+export interface ExportSection<T = unknown> {
+    sectionId: SectionId;
+    data: T;
+    /** 文件类分区（skills/agentPresets/pluginFiles/sessions）以真实文件形式进入 ZIP */
+    files?: {
+        relativePath: string;
+        data: Uint8Array;
+    }[];
+    counts: Record<string, number>;
+    warnings: string[];
+}
+export interface ValidationResult {
+    valid: boolean;
+    issues: {
+        path: string;
+        message: string;
+        severity: 'error' | 'warning';
+    }[];
+}
+export interface SensitiveHit {
+    path: string;
+    field: string;
+}
+export interface SecretScanner {
+    /** 递归扫描 + 剥离敏感字段值；返回清洗后的数据与命中清单（不泄值） */
+    scanAndRedact(data: unknown): {
+        sanitized: unknown;
+        hits: SensitiveHit[];
+    };
+    /** 文本级扫描（文件类分区内容），供强化版使用 */
+    scanText?(text: string): SensitiveHit[];
+}
+export interface NamespaceInfo {
+    value: unknown;
+    base?: unknown;
+    revision: number;
+    applies?: string[];
+    secrets: {
+        path: string[];
+        set: boolean;
+    }[];
+}
+export interface SettingsFacade {
+    /** 读某 namespace（redactSecrets 剥离密钥值）；返回含乐观锁 revision */
+    describe(namespace: string, opts?: {
+        redactSecrets?: boolean;
+    }): Promise<NamespaceInfo>;
+    /** 整体替换（导入/回滚主通道）；expectedRevision 不一致时抛 SETTINGS_CONFLICT 类错误 */
+    replace(namespace: string, value: unknown, expectedRevision?: number): Promise<void>;
+    /** 部分更新（未来 Merge 策略用） */
+    update?(namespace: string, patch: unknown, expectedRevision?: number): Promise<void>;
+}
+export interface CredentialsFacade {
+    /** 只返回状态，永不返回值 */
+    describe(ref: string): Promise<{
+        configured: boolean;
+        source?: string;
+        writable?: boolean;
+    }>;
+    set(ref: string, value: string): Promise<void>;
+    unset(ref: string): Promise<void>;
+}
+export interface PluginInfo {
+    name: string;
+    version: string;
+    enabled: boolean;
+    isBundle?: boolean;
+    inBundles?: string[];
+}
+export interface PluginsFacade {
+    listInstalled(): Promise<PluginInfo[]>;
+    install(pkg: string): Promise<{
+        needsRestart: boolean;
+    }>;
+}
+export interface WorkspaceFacade {
+    listRecords(): Promise<WorkspaceRecord[]>;
+    writeRecord(record: WorkspaceRecord): Promise<void>;
+    removeRecord?(id: string): Promise<void>;
+}
+export interface PatchChange {
+    lineId: string;
+    raw: unknown;
+    action: 'insert' | 'update' | 'remove';
+}
+export interface PatchFileFacade {
+    readPatchLines(file: string): Promise<{
+        lineId: string;
+        raw: unknown;
+    }[]>;
+    applyPatchChanges(file: string, changes: PatchChange[]): Promise<void>;
+}
+export interface FileSystemFacade {
+    readFile(relPath: string): Promise<Uint8Array>;
+    writeFile(relPath: string, data: Uint8Array): Promise<void>;
+    exists(relPath: string): Promise<boolean>;
+    copy(from: string, to: string): Promise<void>;
+    remove(relPath: string): Promise<void>;
+    listRecursive(dir: string): Promise<string[]>;
+    mkdir(dir: string): Promise<void>;
+}
+/** DSH 运行时门面：m3 只依赖此接口；m5 用真实 ctx.settings/credentials/… 实现 */
+export interface HostContext {
+    platform: string;
+    arch: string;
+    homeDir: string;
+    dshVersion: string;
+    log: Logger;
+    settings: SettingsFacade;
+    credentials: CredentialsFacade;
+    plugins: PluginsFacade;
+    workspace: WorkspaceFacade;
+    patchFile: PatchFileFacade;
+    fs: FileSystemFacade;
+}
+export type PlanItemKind = 'Create' | 'Update' | 'Skip' | 'Conflict' | 'Install' | 'MissingSecret' | 'MissingDependency' | 'PathMapping' | 'Warning' | 'Error';
+export type ItemResolution = 'keepCurrent' | 'useImported' | 'review';
+export type GlobalConflictStrategy = 'merge' | 'replace' | 'skipExisting';
+export interface ConflictDecision {
+    itemId: string;
+    resolution: ItemResolution;
+}
+export interface PathMapping {
+    oldPrefix: string;
+    newPrefix: string;
+    appliesTo: ('workspaces' | 'mcp' | 'pluginConfig' | 'skills')[];
+}
+export interface PathIssue {
+    kind: 'missing' | 'platformMismatch' | 'homeMismatch';
+    value: string;
+    mappedTo?: string;
+}
+export interface SnapshotTarget {
+    adapter: SectionId;
+    ref: string;
+}
+export interface PlanItem {
+    id: string;
+    kind: PlanItemKind;
+    adapter: SectionId;
+    description: string;
+    detail?: string;
+    severity: 'info' | 'warning' | 'error';
+    conflict?: ConflictDecision;
+    pathMapping?: PathMapping;
+    missingDependency?: string;
+    target?: SnapshotTarget;
+}
+export interface ApplyResult {
+    ok: boolean;
+    message?: string;
+    needsRestart?: boolean;
+}
+export interface ImportAnalysis {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    compatibility: 'excellent' | 'good' | 'partial' | 'unsupported';
+    sectionsInZip: SectionId[];
+    pluginSummary: {
+        installed: number;
+        toInstall: number;
+    };
+    pathIssues: PathIssue[];
+    secretCount: number;
+    dependencyIssues: {
+        item: string;
+        dependency: string;
+    }[];
+}
+export interface ImportDecisions {
+    strategy: GlobalConflictStrategy;
+    resolutions: Record<string, ItemResolution>;
+    pathMappings: PathMapping[];
+}
+export interface ImportPlan {
+    items: PlanItem[];
+    globalStrategy: GlobalConflictStrategy;
+    pathMappings: PathMapping[];
+    missingSecrets: {
+        ref: string;
+        required: boolean;
+    }[];
+    needsRestart: boolean;
+    estimatedActions: Record<SectionId, number>;
+}
+export interface ExecutedItem {
+    itemId: string;
+    status: 'ok' | 'skipped' | 'failed';
+    message?: string;
+}
+export interface ImportResult {
+    ok: boolean;
+    executed: ExecutedItem[];
+    needsRestart: boolean;
+    missingSecrets: string[];
+    warnings: string[];
+    rollback: RollbackReport | null;
+    snapshotId: string | null;
+}
+export interface ImportContext {
+    manifest: Manifest;
+    targetPlatform: string;
+    /** 目标 DSH 门面（adapter 比较目标状态 / 写入 / 读取数据用） */
+    target: HostContext;
+    /** 已由 PathMapper 处理后的各分区最终数据（adapter.applyItem 从这取写入内容） */
+    sections: Map<SectionId, unknown>;
+    pathMappings: PathMapping[];
+    resolutions: Record<string, ItemResolution>;
+    /** 用户补录的秘密值（仅内存，永不落盘/日志） */
+    secretInputs: Record<string, string>;
+    decryptedCredentials?: Map<string, string>;
+    log: Logger;
+}
+export type SnapshotEntryKind = 'settingsNamespace' | 'credential' | 'patchLine' | 'file' | 'workspaceRecord';
+export interface SnapshotEntry {
+    kind: SnapshotEntryKind;
+    adapter: SectionId;
+    ref: string;
+    /** 原值（credential 条目不含值，仅 existed 标志） */
+    before: unknown;
+    revision?: number;
+    /** file 条目：原文件副本在快照存储中的位置 */
+    copiedTo?: string;
+    /** credential/file 条目：原目标是否存在 */
+    existed?: boolean;
+    /** 所属快照 id（file 条目回滚读取 blob 时使用） */
+    snapshotId?: string;
+}
+export interface Snapshot {
+    id: string;
+    createdAt: string;
+    sourceZip: string;
+    entries: SnapshotEntry[];
+}
+/** 快照存储（默认文件实现见 core/backup.ts；测试可用内存实现） */
+export interface SnapshotStore {
+    save(snapshot: Snapshot, blobs?: Map<string, Uint8Array>): Promise<string>;
+    load(id: string): Promise<Snapshot>;
+    readBlob(id: string, blobPath: string): Promise<Uint8Array>;
+}
+export interface RollbackReport {
+    full: boolean;
+    restored: string[];
+    failed: {
+        item: string;
+        reason: string;
+        manualHint?: string;
+    }[];
+}
+export interface CompatibilityInput {
+    sourceDsh: string;
+    targetDsh: string;
+    sourcePlatform: string;
+    targetPlatform: string;
+    schemaVersion: number;
+    missingSections: SectionId[];
+}
+export type CompatibilityScore = 'excellent' | 'good' | 'partial' | 'unsupported';
+export interface ExportReport {
+    included: {
+        section: SectionId;
+        counts: Record<string, number>;
+    }[];
+    excluded: SectionId[];
+    security: {
+        secretsExcluded: boolean;
+        containsSecrets: boolean;
+        encrypted: boolean;
+        redactedHits: number;
+    };
+    file: {
+        name: string;
+        sizeBytes: number;
+    };
+    warnings: string[];
+}
+export type Portability = 'portable' | 'deviceSpecific' | 'platformSpecific';
+export interface ConfigAdapter<TSection = unknown> {
+    readonly id: SectionId;
+    readonly displayName: string;
+    readonly defaultIncluded: boolean;
+    readonly portability: Portability;
+    /** 读取当前 DSH 该类别配置 → 导出数据（无秘密值） */
+    export(ctx: HostContext, options: ExportOptions): Promise<ExportSection<TSection>>;
+    /** 分析导入数据与目标 DSH 的差异 → 计划项（纯计算，零写入） */
+    analyzeImport(data: TSection, ctx: ImportContext): Promise<PlanItem[]>;
+    /** 执行单个计划项（Importer 引擎按阶段调度） */
+    applyItem(item: PlanItem, ctx: ImportContext): Promise<ApplyResult>;
+    /** 结构校验 */
+    validate(data: TSection): Promise<ValidationResult>;
+    /** 可选：导入前快照（缺省用引擎通用快照） */
+    snapshot?(targets: SnapshotTarget[], ctx: HostContext): Promise<SnapshotEntry[]>;
+    /** 可选：针对本 adapter 的补偿动作 */
+    rollback?(entries: SnapshotEntry[], ctx: HostContext): Promise<void>;
+}
+export interface EncryptionProvider {
+    encrypt(plaintext: string): Promise<{
+        blob: Uint8Array;
+        info: EncryptionInfo;
+    }>;
+    /** authTag 校验失败必须抛错 */
+    decrypt(blob: Uint8Array, info: EncryptionInfo, password: string): Promise<string>;
+}
+/** 导入被确认前拒绝执行（安全阀） */
+export declare class ImportNotConfirmedError extends Error {
+    constructor();
+}
+/** 导入失败：触发回滚后抛出，携带结果供 UI 展示 */
+export declare class ImportFailedError extends Error {
+    readonly result: ImportResult;
+    constructor(message: string, result: ImportResult);
+}

package/lib/core/types.js

@@ -0,0 +1,18 @@
+/* ---------------- 错误类型 ---------------- */
+/** 导入被确认前拒绝执行（安全阀） */
+export class ImportNotConfirmedError extends Error {
+    constructor() {
+        super('导入未确认：必须显式 confirm 后才允许修改任何数据');
+        this.name = 'ImportNotConfirmedError';
+    }
+}
+/** 导入失败：触发回滚后抛出，携带结果供 UI 展示 */
+export class ImportFailedError extends Error {
+    result;
+    constructor(message, result) {
+        super(message);
+        this.name = 'ImportFailedError';
+        this.result = result;
+    }
+}
+//# sourceMappingURL=types.js.map

package/lib/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAoUA,4CAA4C;AAE5C,sBAAsB;AACtB,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD;QACE,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,+BAA+B;AAC/B,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,MAAM,CAAe;IAC9B,YAAY,OAAe,EAAE,MAAoB;QAC/C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/lib/core/validator.d.ts

@@ -0,0 +1,18 @@
+import type { SectionId } from '../schema/types.ts';
+import type { CompatibilityInput, CompatibilityScore, ValidationResult } from './types.ts';
+export { validateManifest } from '../schema/manifest.ts';
+export { validateSectionData } from '../schema/config.ts';
+/** 校验 ZIP 内分区数据集合（空对象=合法）；返回合并的校验结果 */
+export declare function validateSections(sections: ReadonlyMap<SectionId, unknown>): ValidationResult;
+/**
+ * 兼容性评分（规则驱动，不凭感觉）：
+ *  unsupported — schema 超出本插件支持范围（过高/过低）
+ *  partial     — 跨平台、分区缺失、或备份 DSH 比目标新
+ *  good        — 备份 DSH 比目标旧（向后兼容）且其余正常
+ *  excellent   — 同平台、无缺失、schema 支持
+ */
+export declare function computeCompatibility(input: CompatibilityInput): CompatibilityScore;
+/** 兼容性得分的可读描述（UI 报告用） */
+export declare function describeCompatibility(score: CompatibilityScore): string;
+/** 用 describeVersion 生成 schema 状态的用户可读说明 */
+export declare function describeSchemaStatus(schemaVersion: number): string;

package/lib/core/validator.js

@@ -0,0 +1,77 @@
+/**
+ * 整体校验与兼容性评分（规范 §18 完整性 / §30 兼容性评分 / 导入后校验）。
+ */
+import { validateManifest } from "../schema/manifest.js";
+import { validateSectionData } from "../schema/config.js";
+import { canImport, describeVersion } from "../schema/versions.js";
+export { validateManifest } from "../schema/manifest.js";
+export { validateSectionData } from "../schema/config.js";
+/** 校验 ZIP 内分区数据集合（空对象=合法）；返回合并的校验结果 */
+export function validateSections(sections) {
+    const issues = [];
+    for (const [sectionId, data] of sections) {
+        const sectionIssues = validateSectionData(sectionId, data);
+        for (const issue of sectionIssues) {
+            issues.push({ ...issue, path: `${sectionId}:${issue.path}` });
+        }
+    }
+    return { valid: issues.every((i) => i.severity !== 'error'), issues };
+}
+function parseVersion(v) {
+    const m = /^(\d+)\.(\d+)(?:\.(\d+))?(?:-(?:rc\.?)?(\d+))?/i.exec(v);
+    if (!m)
+        return { major: 0, minor: 0, patch: 0, pre: 0 };
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3] ?? 0), pre: Number(m[4] ?? Infinity) };
+}
+/** 版本比较：-1=a<b，0=相等，1=a>b（预发布 < 正式版） */
+function compareVersions(a, b) {
+    for (const k of ['major', 'minor', 'patch']) {
+        if (a[k] !== b[k])
+            return a[k] < b[k] ? -1 : 1;
+    }
+    if (a.pre !== b.pre)
+        return a.pre < b.pre ? -1 : 1;
+    return 0;
+}
+/**
+ * 兼容性评分（规则驱动，不凭感觉）：
+ *  unsupported — schema 超出本插件支持范围（过高/过低）
+ *  partial     — 跨平台、分区缺失、或备份 DSH 比目标新
+ *  good        — 备份 DSH 比目标旧（向后兼容）且其余正常
+ *  excellent   — 同平台、无缺失、schema 支持
+ */
+export function computeCompatibility(input) {
+    if (!canImport(input.schemaVersion))
+        return 'unsupported';
+    let score = 'excellent';
+    if (input.sourcePlatform !== input.targetPlatform)
+        score = 'partial';
+    if (input.missingSections.length > 0)
+        score = 'partial';
+    const src = parseVersion(input.sourceDsh);
+    const tgt = parseVersion(input.targetDsh);
+    const cmp = compareVersions(src, tgt);
+    if (cmp > 0) {
+        // 备份来自更新的 DSH → 可能有目标版本不认识的配置
+        score = 'partial';
+    }
+    else if (cmp < 0) {
+        // 备份来自更旧的 DSH → 目标向后兼容
+        score = 'good';
+    }
+    return score;
+}
+/** 兼容性得分的可读描述（UI 报告用） */
+export function describeCompatibility(score) {
+    switch (score) {
+        case 'excellent': return 'Excellent — 完美兼容（同平台、无缺失、schema 支持）';
+        case 'good': return 'Good — 兼容（旧版备份导入新版 DSH）';
+        case 'partial': return 'Partial — 部分兼容（跨平台/分区缺失/版本超前，需人工确认）';
+        case 'unsupported': return 'Unsupported — 不受支持（schema 超出范围）';
+    }
+}
+/** 用 describeVersion 生成 schema 状态的用户可读说明 */
+export function describeSchemaStatus(schemaVersion) {
+    return describeVersion(schemaVersion);
+}
+//# sourceMappingURL=validator.js.map

package/lib/core/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/core/validator.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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.pluginInventory +  -> PluginsFacade       (@deepseek-ai/dsh-host-plugin-inventory
+ *   ctx.pluginMarketplace                            + @deepseek-ai/dsh-plugin-marketplace, web)
+ *   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 marketplace or
+ * workspace services; hard dependencies are the core `settings`/`credentials`
+ * services present in every profile.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** 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[];
+/** 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;
+}
+/**
+ * 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;