@logictan/dsh-config-manager 0.1.60

package/lib/migrations/index.d.ts

@@ -0,0 +1,29 @@
+export interface MigrationStep {
+    from: number;
+    to: number;
+    /** 纯函数式转换：输入旧结构 → 输出新结构（不触碰目标 DSH） */
+    migrate(doc: unknown): unknown;
+}
+export interface MigrationResult {
+    doc: unknown;
+    migratedFrom: number;
+    applied: {
+        from: number;
+        to: number;
+    }[];
+}
+/**
+ * 迁移注册表：按 from 升序的链式步骤。
+ * 当前只有 v1→v2 占位（CURRENT=1 时不会触发，schema v2 发布后生效）。
+ */
+export declare const MIGRATIONS: MigrationStep[];
+/** 注册新迁移步骤（供未来版本追加；保持链式无环：from 严格递增） */
+export declare function registerMigration(step: MigrationStep): void;
+/**
+ * 沿迁移链把文档升级到目标版本（缺省当前版本）。
+ * - 已是目标版本 → 原样返回；
+ * - 高于目标 → UnsupportedSchemaError（需升级插件）；
+ * - 低于最低支持 → UnsupportedSchemaError；
+ * - 无可用迁移路径 → 抛错。
+ */
+export declare function migrateToCurrent(doc: unknown, fromVersion: number, targetVersion?: number): MigrationResult;

package/lib/migrations/index.js

@@ -0,0 +1,56 @@
+/**
+ * 迁移链（设计 §10）：schemaVersion 独立演进，迁移逻辑集中于此。
+ * 当前 v1 为起点（CURRENT_SCHEMA_VERSION=1），未来 schema v2 发布时：
+ *   1) 新增 src/migrations/v1-to-v2.ts 的迁移函数；
+ *   2) 在下方 MIGRATIONS 注册；业务代码零版本判断（统一走 migrateToCurrent）。
+ */
+import { CURRENT_SCHEMA_VERSION, MIN_SUPPORTED_SCHEMA_VERSION, UnsupportedSchemaError } from '../schema/versions.js';
+import { V1_TO_V2 } from './v1-to-v2.js';
+/**
+ * 迁移注册表：按 from 升序的链式步骤。
+ * 当前只有 v1→v2 占位（CURRENT=1 时不会触发，schema v2 发布后生效）。
+ */
+export const MIGRATIONS = [V1_TO_V2];
+/** 注册新迁移步骤（供未来版本追加；保持链式无环：from 严格递增） */
+export function registerMigration(step) {
+    const dup = MIGRATIONS.find((s) => s.from === step.from || s.to === step.to);
+    if (dup)
+        throw new Error(`迁移步骤冲突: ${step.from}→${step.to} 与 ${dup.from}→${dup.to} 重叠`);
+    MIGRATIONS.push(step);
+    MIGRATIONS.sort((a, b) => a.from - b.from);
+}
+/**
+ * 沿迁移链把文档升级到目标版本（缺省当前版本）。
+ * - 已是目标版本 → 原样返回；
+ * - 高于目标 → UnsupportedSchemaError（需升级插件）；
+ * - 低于最低支持 → UnsupportedSchemaError；
+ * - 无可用迁移路径 → 抛错。
+ */
+export function migrateToCurrent(doc, fromVersion, targetVersion = CURRENT_SCHEMA_VERSION) {
+    if (fromVersion === targetVersion) {
+        return { doc, migratedFrom: fromVersion, applied: [] };
+    }
+    if (fromVersion > targetVersion) {
+        throw new UnsupportedSchemaError(fromVersion, `备份 schema v${fromVersion} 高于当前 v${targetVersion}，需升级本插件`);
+    }
+    if (fromVersion < MIN_SUPPORTED_SCHEMA_VERSION) {
+        throw new UnsupportedSchemaError(fromVersion, `备份 schema v${fromVersion} 低于最低支持 v${MIN_SUPPORTED_SCHEMA_VERSION}`);
+    }
+    let current = doc;
+    let version = fromVersion;
+    const applied = [];
+    while (version < targetVersion) {
+        const step = MIGRATIONS.find((s) => s.from === version && s.to <= targetVersion);
+        if (!step) {
+            throw new UnsupportedSchemaError(version, `没有从 schema v${version} 到 v${targetVersion} 的迁移路径`);
+        }
+        if (step.to <= step.from) {
+            throw new Error(`迁移步骤 ${step.from}→${step.to} 未前进（注册表损坏）`);
+        }
+        current = step.migrate(current);
+        applied.push({ from: step.from, to: step.to });
+        version = step.to;
+    }
+    return { doc: current, migratedFrom: fromVersion, applied };
+}
+//# sourceMappingURL=index.js.map

package/lib/migrations/v1-to-v2.d.ts

@@ -0,0 +1,9 @@
+/**
+ * v1 → v2 迁移（占位）：Export Schema 发布 v2 时在此实现真实转换并注册。
+ * 当前 CURRENT_SCHEMA_VERSION=1，本步骤不会触发（migrateToCurrent 目标=1）。
+ *
+ * 迁移必须是纯函数式：输入 v1 结构 → 输出 v2 结构，绝不触碰目标 DSH。
+ */
+import type { MigrationStep } from './index.ts';
+/** v1→v2 转换（占位实现：v2 尚不存在，仅结构骨架） */
+export declare const V1_TO_V2: MigrationStep;

package/lib/migrations/v1-to-v2.js

@@ -0,0 +1,10 @@
+/** v1→v2 转换（占位实现：v2 尚不存在，仅结构骨架） */
+export const V1_TO_V2 = {
+    from: 1,
+    to: 2,
+    migrate(doc) {
+        // TODO(schema-v2): 例如 settings 分区结构变更时在此改写；当前原样返回
+        return doc;
+    },
+};
+//# sourceMappingURL=v1-to-v2.js.map

package/lib/profiles/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Profiles 模块公共出口（m8，Phase 6）。
+ */
+export { ProfileManager, APPLY_ORDER, isValidProfileName, encodeSections, decodeSections, type ProfileManagerOptions, type ProfileMeta, type StoredProfile, type SwitchPreview, type ProfileSwitchResult, } from './profile-manager.ts';

package/lib/profiles/index.js

@@ -0,0 +1,5 @@
+/**
+ * Profiles 模块公共出口（m8，Phase 6）。
+ */
+export { ProfileManager, APPLY_ORDER, isValidProfileName, encodeSections, decodeSections, } from './profile-manager.js';
+//# sourceMappingURL=index.js.map

package/lib/profiles/profile-manager.d.ts

@@ -0,0 +1,106 @@
+import type { ConfigAdapter, ExecutedItem, GlobalConflictStrategy, HostContext, ItemResolution, PlanItem, RollbackReport, SnapshotStore, TransactionSnapshotContext } from '../core/types.ts';
+import type { SectionId } from '../schema/types.ts';
+export interface ProfileMeta {
+    name: string;
+    createdAt: string;
+    updatedAt: string;
+    sections: SectionId[];
+    fileCount: number;
+}
+/** profile.json 的磁盘形状（文件类分区 data 为 base64） */
+export interface StoredProfile {
+    name: string;
+    version: 1;
+    createdAt: string;
+    updatedAt: string;
+    sections: Partial<Record<SectionId, unknown>>;
+}
+export interface SwitchPreview {
+    items: PlanItem[];
+    missingSecrets: {
+        ref: string;
+        required: boolean;
+    }[];
+    needsRestart: boolean;
+    sectionsInProfile: SectionId[];
+}
+export interface ProfileSwitchResult {
+    ok: boolean;
+    executed: ExecutedItem[];
+    needsRestart: boolean;
+    missingSecrets: string[];
+    warnings: string[];
+    rollback: RollbackReport | null;
+    snapshotId: string | null;
+}
+export interface ProfileManagerOptions {
+    /** Profile 根目录（建议 ~/.dsh/dsh-config-manager，绝对路径） */
+    dataDir: string;
+    ctx: HostContext;
+    adapters: ConfigAdapter[];
+    snapshotStore: SnapshotStore;
+    /** Save/切换涉及的默认分区（缺省 = adapter.defaultIncluded 的分区） */
+    includeSections?: SectionId[];
+}
+/** 执行阶段顺序（与 core/analyzer.ts APPLY_ORDER 对齐：副作用大的 patch/安装最后） */
+export declare const APPLY_ORDER: readonly SectionId[];
+/** Profile 名校验：拒绝路径穿越与非法字符 */
+export declare function isValidProfileName(name: string): boolean;
+/** Profile 落盘编码：文件类分区 files[].data(Uint8Array) → base64；JSON 分区原样（已可序列化） */
+export declare function encodeSections(sections: ReadonlyMap<SectionId, unknown>): Partial<Record<SectionId, unknown>>;
+/** Profile 读入解码：base64 → Uint8Array */
+export declare function decodeSections(encoded: Partial<Record<SectionId, unknown>>): Map<SectionId, unknown>;
+export declare class ProfileManager {
+    private readonly dataDir;
+    private readonly ctx;
+    private readonly adapters;
+    private readonly snapshotStore;
+    private readonly includeSections;
+    private readonly profilesDir;
+    constructor(options: ProfileManagerOptions);
+    list(): Promise<ProfileMeta[]>;
+    private profileDir;
+    private profileFile;
+    private meta;
+    private readStored;
+    private writeStored;
+    /** 保存当前 DSH 配置为 Profile（复用 adapter.export，天然不含秘密值） */
+    saveCurrent(name: string, opts?: {
+        sections?: SectionId[];
+    }): Promise<ProfileMeta>;
+    /** 复制 Profile（含全部分区数据） */
+    duplicate(name: string, newName: string): Promise<ProfileMeta>;
+    /** 重命名 Profile（目录级移动） */
+    rename(oldName: string, newName: string): Promise<ProfileMeta>;
+    /** 删除 Profile */
+    delete(name: string): Promise<void>;
+    private exists;
+    /** 只读读取 profile 的分区数据（Phase 7 迁移前咨询用；零写入） */
+    readSections(name: string): Promise<Map<SectionId, unknown>>;
+    /** Preview（纯读，零写入）：分析切换到该 Profile 会产生的计划项 */
+    analyzeSwitch(name: string): Promise<SwitchPreview>;
+    /** 执行切换：confirm → Snapshot → 分阶段 apply → 失败 rollback（与导入同一安全语义） */
+    executeSwitch(name: string, opts?: {
+        confirm?: boolean;
+        strategy?: GlobalConflictStrategy;
+        resolutions?: Record<string, ItemResolution>;
+        secretInputs?: Record<string, string>;
+        decryptedCredentials?: Map<string, string>;
+        rollbackOnError?: boolean;
+        /** Phase 4 生产 journal↔snapshot 绑定（deferred）；不传 = 无 journal 绑定 */
+        snapshotBinding?: TransactionSnapshotContext;
+    }): Promise<ProfileSwitchResult>;
+    /** 逐分区 validate + analyzeImport（纯计算；MissingSecret 兜底与 analyzer.ensureMissingSecrets 等价） */
+    private analyzeSections;
+    /** 单计划项执行（语义对齐 core/analyzer.ts applyOne） */
+    private applyOne;
+    /** 导出 Profile 为单 JSON 文件（dsh-profile-<name>.json，自包含可分发；文件类数据 base64 内嵌） */
+    exportProfile(name: string, outPath: string): Promise<{
+        path: string;
+        fileCount: number;
+    }>;
+    /** 导入 Profile 文件（JSON 校验 + 存入 profiles 目录；同名已存在默认拒绝） */
+    importProfile(filePath: string, opts?: {
+        asName?: string;
+    }): Promise<ProfileMeta>;
+}