dsh-desktop-kit 0.0.0-stage → 2.0.0

package/plugins/dsh-profile-transfer/transfer.js

@@ -0,0 +1,1004 @@
+/**
+ * dsh-profile-transfer — перенос профиля DSH между машинами.
+ *
+ * Чистый Node-модуль без зависимостей: собирает выбранные части домашней папки DSH
+ * (`~/.dsh`) и профиля в один `.tar.gz`, а затем безопасно разворачивает его на
+ * другой машине (с бэкапом текущего состояния). Host-плагин в index.js даёт к этому
+ * RPC-доступ, client.js — страницу настроек.
+ *
+ * Формат архива:
+ *   manifest.json
+ *   payload/dsh/...                                  файлы из домашней папки DSH
+ *   payload/profiles/<profile>/...                    файлы профиля (package.json, patch, lock)
+ *   payload/local-plugins/<package>/...               исходники локальных link:-плагинов
+ *   payload/skills/...                                навыки
+ *   payload/memory/...                                память (memory/)
+ *   payload/projects-memory/...                       память проектов
+ *   payload/sessions/...                              сессии (опционально)
+ *   payload/attachments/...                           вложения (опционально)
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import zlib from "node:zlib";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+const PLUGIN_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const BOOTSTRAP_PLUGIN_FILES = ["package.json", "index.js", "client.js", "transfer.js", "cordis.patch.yml", "icon.svg", "README.md"];
+
+export const FORMAT = "dsh-profile-transfer";
+export const FORMAT_VERSION = 1;
+const EXCLUDED_NAMES = new Set(["node_modules", ".git", ".DS_Store", "Thumbs.db"]);
+const WORKSPACE_FOLDER_EXCLUDES = new Set(["pgruntime", ".venv", "venv", "__pycache__", ".pytest_cache", ".mypy_cache", ".cache", ".next", "coverage", "tmp"]);
+const MAX_WORKSPACE_FOLDER_BYTES = 1024 * 1024 * 1024;
+const MAX_WORKSPACE_FOLDER_FILES = 250000;
+const SKIP_DSH_TOP_LEVEL = new Set([
+  "profiles",
+  "skills",
+  "memory",
+  "projects-memory",
+  "sessions",
+  "attachments",
+  "cache",
+  "logs",
+  "storages",
+  "dsh-runtimes",
+  "dsh-market",
+  ".dsh-market",
+  "backup-import",
+  "backup-session-move-install-2026-11-04",
+]);
+
+/* ------------------------------------------------------------------ */
+/* tar (ustar) writer / reader                                        */
+/* ------------------------------------------------------------------ */
+
+function pad(value, size) {
+  const buffer = Buffer.alloc(size, 0);
+  buffer.write(String(value), 0, size, "utf8");
+  return buffer;
+}
+
+function octal(value, size) {
+  return `${(value >>> 0).toString(8).padStart(size - 1, "0")}\0`;
+}
+
+/** Split a path into ustar name (100) and prefix (155). */
+function tarNameParts(relativePath) {
+  const normalized = relativePath.replaceAll("\\", "/").replace(/^\/+/u, "");
+  const bytes = Buffer.byteLength(normalized, "utf8");
+  if (bytes <= 100) return { name: normalized, prefix: "" };
+  const parts = normalized.split("/");
+  for (let index = parts.length - 1; index > 0; index -= 1) {
+    const prefix = parts.slice(0, index).join("/");
+    const name = parts.slice(index).join("/");
+    if (Buffer.byteLength(name, "utf8") <= 100 && Buffer.byteLength(prefix, "utf8") <= 155) return { name, prefix };
+  }
+  throw new Error(`path is too long for tar: ${relativePath}`);
+}
+
+function tarHeader({ relativePath, size, mode = 0o644, type = "0", mtime = Math.floor(Date.now() / 1000) }) {
+  const { name, prefix } = tarNameParts(relativePath);
+  const header = Buffer.alloc(512, 0);
+  header.write(name, 0, 100, "utf8");
+  header.write(octal(mode, 8), 100, 8, "ascii");
+  header.write(octal(0, 8), 108, 8, "ascii");
+  header.write(octal(0, 8), 116, 8, "ascii");
+  header.write(octal(size, 12), 124, 12, "ascii");
+  header.write(octal(mtime, 12), 136, 12, "ascii");
+  header.write("        ", 148, 8, "ascii");
+  header.write(type, 156, 1, "ascii");
+  header.write("ustar\0", 257, 6, "ascii");
+  header.write("00", 263, 2, "ascii");
+  header.write(prefix, 345, 155, "utf8");
+  let sum = 0;
+  for (const byte of header) sum += byte;
+  header.write(octal(sum, 7), 148, 7, "ascii");
+  header.write(" ", 155, 1, "ascii");
+  return header;
+}
+
+function createTarGz() {
+  const chunks = [];
+  const addFile = (relativePath, bytes, stat) => {
+    const buffer = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+    chunks.push(tarHeader({
+      relativePath,
+      size: buffer.length,
+      mode: stat?.mode ? stat.mode & 0o777 : 0o644,
+      mtime: stat?.mtime ? Math.floor(stat.mtimeMs / 1000) : Math.floor(Date.now() / 1000),
+    }));
+    chunks.push(buffer);
+    const remainder = buffer.length % 512;
+    if (remainder !== 0) chunks.push(Buffer.alloc(512 - remainder, 0));
+  };
+  const addDirectory = (relativePath, stat) => {
+    chunks.push(tarHeader({
+      relativePath: relativePath.endsWith("/") ? relativePath : `${relativePath}/`,
+      size: 0,
+      mode: stat?.mode ? stat.mode & 0o777 : 0o755,
+      type: "5",
+      mtime: stat?.mtime ? Math.floor(stat.mtimeMs / 1000) : Math.floor(Date.now() / 1000),
+    }));
+  };
+  const finish = () => {
+    chunks.push(Buffer.alloc(1024, 0));
+    return zlib.gzipSync(Buffer.concat(chunks), { level: 6 });
+  };
+  return { addFile, addDirectory, finish };
+}
+
+function parseOctal(buffer) {
+  const text = buffer.toString("ascii").replace(/\0.*$/u, "").trim();
+  if (text.length === 0) return 0;
+  return Number.parseInt(text, 8) || 0;
+}
+
+function parseTarGz(archive) {
+  const tar = zlib.gunzipSync(archive);
+  const entries = [];
+  let offset = 0;
+  while (offset + 512 <= tar.length) {
+    const header = tar.subarray(offset, offset + 512);
+    if (header.every((byte) => byte === 0)) break;
+    const name = header.subarray(0, 100).toString("utf8").replace(/\0.*$/u, "");
+    const prefix = header.subarray(345, 500).toString("utf8").replace(/\0.*$/u, "");
+    const size = parseOctal(header.subarray(124, 136));
+    const type = String.fromCharCode(header[156] || 48);
+    const relativePath = prefix.length > 0 ? `${prefix}/${name}` : name;
+    offset += 512;
+    const data = tar.subarray(offset, offset + size);
+    offset += size + ((512 - (size % 512)) % 512);
+    if (relativePath.length === 0) continue;
+    entries.push({ path: relativePath, type, data });
+  }
+  return entries;
+}
+
+/* ------------------------------------------------------------------ */
+/* paths and manifest                                                 */
+/* ------------------------------------------------------------------ */
+
+export function defaultHome() {
+  return process.env.DSH_HOME ?? path.join(os.homedir(), ".dsh");
+}
+
+function safeRelative(relativePath) {
+  const normalized = String(relativePath).replaceAll("\\", "/");
+  if (normalized.startsWith("/") || /^[A-Za-z]:/u.test(normalized)) throw new Error(`unsafe archive path: ${relativePath}`);
+  const segments = normalized.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new Error(`unsafe archive path: ${relativePath}`);
+  }
+  return segments.join("/");
+}
+
+function walkFiles(root, relativePrefix, options = {}) {
+  const results = [];
+  results.capped = false;
+  const exclude = options.exclude ?? new Set();
+  const extraExcludedNames = options.excludeNames ?? new Set();
+  const maxFiles = Number.isFinite(options.maxFiles) ? Math.max(1, Number(options.maxFiles)) : Infinity;
+  const walk = (current, relative) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (results.length >= maxFiles) {
+        results.capped = true;
+        return;
+      }
+      if (EXCLUDED_NAMES.has(entry.name) || extraExcludedNames.has(entry.name)) continue;
+      const absolute = path.join(current, entry.name);
+      const nextRelative = relative.length === 0 ? entry.name : `${relative}/${entry.name}`;
+      if (exclude.has(nextRelative) || exclude.has(entry.name)) continue;
+      let stat;
+      try {
+        stat = entry.isSymbolicLink() ? undefined : fs.statSync(absolute);
+      } catch {
+        continue;
+      }
+      if (entry.isDirectory()) walk(absolute, nextRelative);
+      else if (stat !== undefined && stat.isFile()) {
+        results.push({
+          source: absolute,
+          relative: relativePrefix.length === 0 ? nextRelative : `${relativePrefix}/${nextRelative}`,
+          size: stat.size,
+          mtimeMs: stat.mtimeMs,
+        });
+      }
+    }
+  };
+  walk(root, "");
+  return results;
+}
+
+function sizeOf(files) {
+  return files.reduce((total, file) => total + file.size, 0);
+}
+
+function humanSize(bytes) {
+  if (bytes < 1024) return `${bytes} Б`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} КБ`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} МБ`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} ГБ`;
+}
+
+function isSafePackageName(name) {
+  return typeof name === "string" && /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/iu.test(name) && !name.includes("..");
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function sha256(bytes) {
+  return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+
+/* ------------------------------------------------------------------ */
+/* collection plan                                                    */
+/* ------------------------------------------------------------------ */
+
+const DEFAULT_SELECTION = {
+  profile: true,
+  localPlugins: true,
+  workspaces: true,
+  workspaceFolders: false,
+  skills: true,
+  memory: true,
+  projectsMemory: true,
+  sessions: false,
+  attachments: false,
+  credentials: false,
+  config: true,
+};
+
+export function normalizeSelection(selection) {
+  const result = { ...DEFAULT_SELECTION };
+  if (selection !== null && typeof selection === "object") {
+    for (const key of Object.keys(DEFAULT_SELECTION)) {
+      if (typeof selection[key] === "boolean") result[key] = selection[key];
+    }
+  }
+  return result;
+}
+
+function profileDirectory(home, profileName) {
+  return path.join(home, "profiles", profileName);
+}
+
+function localPluginTargets(home, profileName) {
+  const directory = profileDirectory(home, profileName);
+  const manifest = readJson(path.join(directory, "package.json"));
+  const dependencies = manifest?.dependencies !== null && typeof manifest?.dependencies === "object" ? manifest.dependencies : {};
+  const targets = [];
+  for (const [packageName, spec] of Object.entries(dependencies)) {
+    if (typeof spec !== "string") continue;
+    const match = spec.match(/^(?:link|file):(.+)$/u);
+    if (match === null) continue;
+    let target = match[1].replaceAll("/", path.sep);
+    if (!path.isAbsolute(target)) target = path.resolve(directory, target);
+    targets.push({ packageName, spec, target });
+  }
+  return targets;
+}
+
+/** Workspaces from the local registry that have an absolute folder path. */
+function workspaceDirectories(home) {
+  const registry = readJson(path.join(home, "storages", "workspace.json"));
+  const tables = registry?.tables?.workspaces;
+  if (tables === null || typeof tables !== "object") return [];
+  return Object.entries(tables)
+    .map(([id, workspace]) => ({
+      id,
+      title: typeof workspace?.title === "string" && workspace.title.length > 0 ? workspace.title : id,
+      path: typeof workspace?.path === "string" ? workspace.path : null,
+    }))
+    .filter((workspace) => typeof workspace.path === "string" && workspace.path.length > 0 && path.isAbsolute(workspace.path));
+}
+
+function workspaceFolderName(id) {
+  return String(id).replace(/[^A-Za-z0-9_-]/gu, "_");
+}
+
+/** Files and per-workspace stats for the optional "workspace folders" group. */
+function workspaceFolderEntries(home, options = {}) {
+  const maxFiles = Number.isFinite(options.maxFiles) ? Math.max(1, Number(options.maxFiles)) : 8000;
+  const entries = [];
+  const workspaces = [];
+  let capped = false;
+  for (const workspace of workspaceDirectories(home)) {
+    let exists = false;
+    try {
+      exists = fs.statSync(workspace.path).isDirectory();
+    } catch {
+      exists = false;
+    }
+    const relative = `payload/workspace-folders/${workspaceFolderName(workspace.id)}`;
+    const files = exists ? walkFiles(workspace.path, relative, { maxFiles, excludeNames: WORKSPACE_FOLDER_EXCLUDES }) : [];
+    if (files.capped === true) capped = true;
+    entries.push(...files);
+    workspaces.push({
+      id: workspace.id,
+      title: workspace.title,
+      path: workspace.path,
+      relative,
+      exists,
+      files: files.length,
+      bytes: sizeOf(files),
+      human: humanSize(sizeOf(files)),
+    });
+  }
+  return { entries, workspaces, capped };
+}
+
+/**
+ * Describe every exportable group with its real size on disk, so the UI can
+ * show what will be included before the user presses the button.
+ */
+export function describeSources(options = {}) {
+  const home = options.home ?? defaultHome();
+  const profileName = options.profile ?? "desktop";
+  const selection = normalizeSelection(options.selection);
+  const groups = [];
+
+  const addGroup = (id, label, description, files, available) => {
+    groups.push({ id, label, description, available, files: files.length, bytes: sizeOf(files), human: humanSize(sizeOf(files)) });
+  };
+
+  const profileDir = profileDirectory(home, profileName);
+  const profileFiles = ["package.json", "cordis.patch.yml", "cordis.yml", "pnpm-lock.yaml", ".npmrc"]
+    .map((name) => path.join(profileDir, name))
+    .filter((filePath) => fs.existsSync(filePath))
+    .map((filePath) => {
+      const stat = fs.statSync(filePath);
+      return { source: filePath, relative: `payload/profiles/${profileName}/${path.basename(filePath)}`, size: stat.size, mtimeMs: stat.mtimeMs };
+    });
+  addGroup("profile", "Профиль", "package.json, cordis.patch.yml, cordis.yml, pnpm-lock.yaml (без node_modules)", profileFiles, fs.existsSync(profileDir));
+
+  const plugins = localPluginTargets(home, profileName);
+  const pluginFiles = plugins.flatMap((plugin) => walkFiles(plugin.target, `payload/local-plugins/${plugin.packageName}`));
+  addGroup("localPlugins", "Локальные плагины", "исходники плагинов, установленных из папок (link:)", pluginFiles, plugins.length > 0);
+
+  const workspaceStorage = path.join(home, "storages", "workspace.json");
+  const workspaceFiles = fs.existsSync(workspaceStorage)
+    ? [{ source: workspaceStorage, relative: "payload/workspaces/workspace.json", size: fs.statSync(workspaceStorage).size }]
+    : [];
+  addGroup("workspaces", "Рабочие области", "реестр рабочих областей: названия, папки, закрепление и группировка чатов", workspaceFiles, workspaceFiles.length > 0);
+
+  const workspaceFolderPlan = workspaceFolderEntries(home, { maxFiles: 8000 });
+  const workspaceFolderFiles = workspaceFolderPlan.entries;
+  const workspaceFolderGroup = {
+    id: "workspaceFolders",
+    label: "Папки рабочих областей",
+    description: "код и артефакты папок рабочих областей (кроме node_modules/pgruntime/tmp) — может быть много гигабайт",
+    available: workspaceFolderPlan.workspaces.some((workspace) => workspace.exists),
+    files: workspaceFolderFiles.length,
+    bytes: sizeOf(workspaceFolderFiles),
+    human: humanSize(sizeOf(workspaceFolderFiles)),
+    capped: workspaceFolderPlan.capped,
+    workspaces: workspaceFolderPlan.workspaces,
+  };
+  groups.push(workspaceFolderGroup);
+
+  const skillsDir = path.join(home, "skills");
+  const skillFiles = walkFiles(skillsDir, "payload/skills");
+  addGroup("skills", "Навыки", "все файловые навыки (без node_modules)", skillFiles, fs.existsSync(skillsDir));
+
+  const memoryDir = path.join(home, "memory");
+  const memoryFiles = walkFiles(memoryDir, "payload/memory");
+  addGroup("memory", "Память", "memory/ — журнал сессий, досье проектов, окружение", memoryFiles, fs.existsSync(memoryDir));
+
+  const projectsMemoryDir = path.join(home, "projects-memory");
+  const projectsMemoryFiles = walkFiles(projectsMemoryDir, "payload/projects-memory", {
+    exclude: new Set(["_access.log", "_state.json"]),
+  });
+  addGroup("projectsMemory", "Память проектов", "projects-memory/ — досье и журналы проектов", projectsMemoryFiles, fs.existsSync(projectsMemoryDir));
+
+  const configFiles = ["AGENTS.md", "dream-skin.json"]
+    .map((name) => path.join(home, name))
+    .filter((filePath) => fs.existsSync(filePath))
+    .map((filePath) => {
+      const stat = fs.statSync(filePath);
+      return { source: filePath, relative: `payload/dsh/${path.basename(filePath)}`, size: stat.size, mtimeMs: stat.mtimeMs };
+    });
+  addGroup("config", "Глобальные конфиги", "AGENTS.md, dream-skin.json", configFiles, configFiles.length > 0);
+
+  const sessionsDir = path.join(home, "sessions");
+  const sessionFiles = walkFiles(sessionsDir, "payload/sessions", { maxFiles: 4000 });
+  const sessionsGroup = { id: "sessions", label: "История сессий", description: "sessions/ — может быть очень большим", available: fs.existsSync(sessionsDir), files: sessionFiles.length, bytes: sizeOf(sessionFiles), human: humanSize(sizeOf(sessionFiles)), capped: sessionFiles.capped === true };
+  groups.push(sessionsGroup);
+
+  const attachmentsDir = path.join(home, "attachments");
+  const attachmentFiles = walkFiles(attachmentsDir, "payload/attachments", { maxFiles: 2000 });
+  groups.push({ id: "attachments", label: "Вложения", description: "attachments/ — картинки и файлы из чатов", available: fs.existsSync(attachmentsDir), files: attachmentFiles.length, bytes: sizeOf(attachmentFiles), human: humanSize(sizeOf(attachmentFiles)), capped: attachmentFiles.capped === true });
+
+  const credentialsFile = path.join(home, ".credentials.yaml");
+  const credentialsFiles = fs.existsSync(credentialsFile)
+    ? [{
+      source: credentialsFile,
+      relative: "payload/dsh/.credentials.yaml",
+      size: fs.statSync(credentialsFile).size,
+      mtimeMs: fs.statSync(credentialsFile).mtimeMs,
+    }]
+    : [];
+  addGroup("credentials", "Секреты", ".credentials.yaml — токены и ключи доступа (переносить только на доверенную машину)", credentialsFiles, credentialsFiles.length > 0);
+
+  return { home, profile: profileName, selection, groups };
+}
+
+function collectEntries(description) {
+  const selected = description.selection;
+  const map = new Map(description.groups.map((group) => [group.id, group]));
+  const entries = [];
+  const ids = ["profile", "localPlugins", "workspaces", "skills", "memory", "projectsMemory", "config"];
+  if (selected.workspaceFolders === true) ids.push("workspaceFolders");
+  if (selected.sessions) ids.push("sessions");
+  if (selected.attachments) ids.push("attachments");
+  if (selected.credentials) ids.push("credentials");
+  const activeIds = new Set(ids.filter((id) => selected[id] !== false));
+  const fileGroups = ["profile", "localPlugins", "workspaces", "workspaceFolders", "skills", "memory", "projectsMemory", "config", "sessions", "attachments", "credentials"];
+  for (const id of fileGroups) {
+    if (!activeIds.has(id)) continue;
+    const group = map.get(id);
+    if (group === undefined) continue;
+    for (const item of groupFiles(description, id)) entries.push(item);
+  }
+  return entries;
+}
+
+/** Re-walk one group because describeSources stores summaries only. */
+function groupFiles(description, id) {
+  const home = description.home;
+  const profileName = description.profile;
+  const profileDir = profileDirectory(home, profileName);
+  switch (id) {
+    case "profile":
+      return ["package.json", "cordis.patch.yml", "cordis.yml", "pnpm-lock.yaml", ".npmrc"]
+        .map((name) => path.join(profileDir, name))
+        .filter((filePath) => fs.existsSync(filePath))
+        .map((filePath) => ({ source: filePath, relative: `payload/profiles/${profileName}/${path.basename(filePath)}`, size: fs.statSync(filePath).size }));
+    case "localPlugins":
+      return localPluginTargets(home, profileName).flatMap((plugin) => walkFiles(plugin.target, `payload/local-plugins/${plugin.packageName}`));
+    case "workspaces":
+      return fs.existsSync(path.join(home, "storages", "workspace.json"))
+        ? [{ source: path.join(home, "storages", "workspace.json"), relative: "payload/workspaces/workspace.json", size: fs.statSync(path.join(home, "storages", "workspace.json")).size }]
+        : [];
+    case "workspaceFolders":
+      return workspaceFolderEntries(home, { maxFiles: MAX_WORKSPACE_FOLDER_FILES }).entries;
+    case "skills":
+      return walkFiles(path.join(home, "skills"), "payload/skills");
+    case "memory":
+      return walkFiles(path.join(home, "memory"), "payload/memory");
+    case "projectsMemory":
+      return walkFiles(path.join(home, "projects-memory"), "payload/projects-memory", { exclude: new Set(["_access.log", "_state.json"]) });
+    case "config":
+      return ["AGENTS.md", "dream-skin.json"]
+        .map((name) => path.join(home, name))
+        .filter((filePath) => fs.existsSync(filePath))
+        .map((filePath) => ({ source: filePath, relative: `payload/dsh/${path.basename(filePath)}`, size: fs.statSync(filePath).size }));
+    case "sessions":
+      return walkFiles(path.join(home, "sessions"), "payload/sessions");
+    case "attachments":
+      return walkFiles(path.join(home, "attachments"), "payload/attachments");
+    case "credentials":
+      return fs.existsSync(path.join(home, ".credentials.yaml"))
+        ? [{ source: path.join(home, ".credentials.yaml"), relative: "payload/dsh/.credentials.yaml", size: fs.statSync(path.join(home, ".credentials.yaml")).size }]
+        : [];
+    default:
+      return [];
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* export                                                             */
+/* ------------------------------------------------------------------ */
+
+/** Files placed at the archive root so the clean-machine bootstrap is easy to find. */
+function bootstrapArchiveFiles() {
+  const files = [];
+  const add = (absolute, relative) => {
+    if (!fs.existsSync(absolute)) return;
+    files.push({ absolute, relative, stat: fs.statSync(absolute) });
+  };
+  // ASCII names: Windows bsdtar mis-decodes non-ASCII tar entry names.
+  add(path.join(PLUGIN_ROOT, "bootstrap", "01-INSTALL.cmd"), "01-INSTALL.cmd");
+  add(path.join(PLUGIN_ROOT, "bootstrap", "install-on-clean-machine.ps1"), "install-on-clean-machine.ps1");
+  add(path.join(PLUGIN_ROOT, "bootstrap", "README-ARCHIVE.md"), "README-INSTALL.md");
+  for (const name of BOOTSTRAP_PLUGIN_FILES) {
+    add(path.join(PLUGIN_ROOT, name), `bootstrap-plugin/dsh-profile-transfer/${name}`);
+  }
+  const localeDirectory = path.join(PLUGIN_ROOT, "locale");
+  if (fs.existsSync(localeDirectory)) {
+    for (const name of fs.readdirSync(localeDirectory)) {
+      add(path.join(localeDirectory, name), `bootstrap-plugin/dsh-profile-transfer/locale/${name}`);
+    }
+  }
+  return files;
+}
+
+export function exportBundle(options = {}) {
+  const home = options.home ?? defaultHome();
+  const profileName = options.profile ?? "desktop";
+  const selection = normalizeSelection(options.selection);
+  const description = describeSources({ home, profile: profileName, selection });
+  const entries = collectEntries(description);
+  if (entries.length === 0) throw new Error("не выбрано ни одной группы для экспорта");
+  const workspaceFolderEntriesSelected = entries.filter((entry) => entry.relative.startsWith("payload/workspace-folders/"));
+  const workspaceFolderBytes = sizeOf(workspaceFolderEntriesSelected);
+  if (workspaceFolderEntriesSelected.length > MAX_WORKSPACE_FOLDER_FILES || workspaceFolderBytes > MAX_WORKSPACE_FOLDER_BYTES) {
+    throw new Error(
+      `Папки рабочих областей слишком большие для архива: ${workspaceFolderEntriesSelected.length} файлов, ${humanSize(workspaceFolderBytes)}. ` +
+      `Лимит — ${MAX_WORKSPACE_FOLDER_FILES} файлов и ${humanSize(MAX_WORKSPACE_FOLDER_BYTES)}. Скопируйте папки проектов вручную.`,
+    );
+  }
+  const destinationDirectory = options.destinationDirectory ?? path.join(os.homedir(), "Documents", "DSH-обмены");
+  fs.mkdirSync(destinationDirectory, { recursive: true });
+  const timestamp = new Date().toISOString().replace(/[:.]/gu, "-").slice(0, 19);
+  const archivePath = options.archivePath ?? path.join(destinationDirectory, `dsh-profile-${timestamp}.tar.gz`);
+  const tar = createTarGz();
+  // Root-level bootstrap first: on a clean machine the user sees УСТАНОВИТЬ.cmd
+  // immediately after extracting the archive, without digging into payload/.
+  const bootstrapFiles = bootstrapArchiveFiles();
+  for (const file of bootstrapFiles) {
+    try {
+      const bytes = fs.readFileSync(file.absolute);
+      tar.addFile(safeRelative(file.relative), bytes, file.stat);
+    } catch {
+      /* a missing bootstrap resource must not break the data export */
+    }
+  }
+  const files = [];
+  const seen = new Set();
+  for (const entry of entries) {
+    if (seen.has(entry.relative)) continue;
+    seen.add(entry.relative);
+    let bytes;
+    try {
+      bytes = fs.readFileSync(entry.source);
+    } catch {
+      continue;
+    }
+    tar.addFile(safeRelative(entry.relative), bytes, fs.statSync(entry.source));
+    files.push({ path: safeRelative(entry.relative), size: bytes.length, sha256: sha256(bytes) });
+  }
+  const manifest = {
+    format: FORMAT,
+    version: FORMAT_VERSION,
+    createdAt: new Date().toISOString(),
+    host: os.hostname(),
+    platform: `${process.platform}-${process.arch}`,
+    dshVersion: process.env.DSH_CLIENT_VERSION ?? process.env.DSH_VERSION ?? "unknown",
+    profile: profileName,
+    selection,
+    totals: { files: files.length, bytes: files.reduce((total, file) => total + file.size, 0), human: humanSize(files.reduce((total, file) => total + file.size, 0)) },
+    localPlugins: localPluginTargets(home, profileName).map((plugin) => ({ packageName: plugin.packageName, spec: plugin.spec })),
+    origin: { userHome: os.homedir(), dshHome: home, platform: process.platform },
+    workspaces: (() => {
+      const workspaceJson = readJson(path.join(home, "storages", "workspace.json"));
+      const tables = workspaceJson?.tables?.workspaces;
+      if (tables === null || typeof tables !== "object") return { count: 0, titles: [] };
+      return { count: Object.keys(tables).length, titles: Object.values(tables).map((workspace) => workspace?.title).filter((title) => typeof title === "string") };
+    })(),
+    workspaceFolders: (() => {
+      const buckets = new Map();
+      for (const entry of workspaceFolderEntriesSelected) {
+        const match = entry.relative.match(/^payload\/workspace-folders\/([^/]+)\//u);
+        if (match === null) continue;
+        const bucket = buckets.get(match[1]) ?? { folder: match[1], files: 0, bytes: 0 };
+        bucket.files += 1;
+        bucket.bytes += entry.size;
+        buckets.set(match[1], bucket);
+      }
+      return workspaceDirectories(home)
+        .filter((workspace) => buckets.has(workspaceFolderName(workspace.id)))
+        .map((workspace) => {
+          const bucket = buckets.get(workspaceFolderName(workspace.id));
+          return { id: workspace.id, title: workspace.title, path: workspace.path, relative: `payload/workspace-folders/${workspaceFolderName(workspace.id)}`, files: bucket.files, bytes: bucket.bytes, human: humanSize(bucket.bytes) };
+        });
+    })(),
+    bootstrap: {
+      installer: "01-INSTALL.cmd",
+      script: "install-on-clean-machine.ps1",
+      readme: "README-INSTALL.md",
+      pluginDirectory: "bootstrap-plugin/dsh-profile-transfer",
+      files: bootstrapFiles.length,
+    },
+    files,
+  };
+  tar.addFile("manifest.json", Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`, "utf8"));
+  const archive = tar.finish();
+  fs.writeFileSync(archivePath, archive);
+  return { archivePath, manifest, bytes: archive.length, human: humanSize(archive.length) };
+}
+
+/* ------------------------------------------------------------------ */
+/* import                                                            */
+/* ------------------------------------------------------------------ */
+
+export function inspectBundle(archivePath) {
+  const archive = fs.readFileSync(archivePath);
+  const entries = parseTarGz(archive);
+  const manifestEntry = entries.find((entry) => entry.path === "manifest.json");
+  if (manifestEntry === undefined) throw new Error("в архиве нет manifest.json — это не архив переноса DSH");
+  const manifest = JSON.parse(manifestEntry.data.toString("utf8"));
+  if (manifest.format !== FORMAT || manifest.version !== FORMAT_VERSION) throw new Error("неизвестный формат архива переноса");
+  const files = entries.filter((entry) => entry.type === "0" && entry.path !== "manifest.json");
+  return {
+    manifest,
+    files: files.map((entry) => ({ path: entry.path, size: entry.data.length })),
+    bytes: archive.length,
+    human: humanSize(archive.length),
+  };
+}
+
+/** Session ids that actually exist under the sessions directory (cwd folder / session-id). */
+function existingSessionIds(home) {
+  const ids = new Set();
+  const root = path.join(home, "sessions");
+  let directories = [];
+  try {
+    directories = fs.readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+  } catch {
+    return ids;
+  }
+  for (const directory of directories) {
+    if (directory.name.startsWith("session-")) {
+      ids.add(directory.name);
+      continue;
+    }
+    let children = [];
+    try {
+      children = fs.readdirSync(path.join(root, directory.name), { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const child of children) {
+      if (child.isDirectory() && child.name.startsWith("session-")) ids.add(child.name);
+    }
+  }
+  return ids;
+}
+
+/** Rewrite paths from the exporting machine to this machine (user home, DSH home). */
+function remapOriginPath(value, origin, home) {
+  if (typeof value !== "string" || value.length === 0) return value;
+  const currentUserHome = os.homedir();
+  const pairs = [];
+  if (typeof origin?.userHome === "string" && origin.userHome.length > 0 && origin.userHome !== currentUserHome) {
+    pairs.push([origin.userHome, currentUserHome]);
+  }
+  if (typeof origin?.dshHome === "string" && origin.dshHome.length > 0 && origin.dshHome !== home) {
+    pairs.push([origin.dshHome, home]);
+  }
+  let result = value;
+  for (const [from, to] of pairs) {
+    const fromLower = from.toLowerCase();
+    if (result.toLowerCase() === fromLower) {
+      result = to;
+      continue;
+    }
+    if (result.toLowerCase().startsWith(fromLower) && /[\\/]/u.test(result[from.length] ?? "")) {
+      result = `${to}${result.slice(from.length)}`;
+    }
+  }
+  return result;
+}
+
+/**
+ * Restore the workspace registry (`~/.dsh/storages/workspace.json`): workspace
+ * names, folder paths, chat grouping, archived/pinned chats. The archive is
+ * merged with the local registry so an import never silently drops local state.
+ */
+function restoreWorkspaceRegistry(home, incoming, manifest) {
+  if (incoming === null || typeof incoming !== "object") return 0;
+  const target = path.join(home, "storages", "workspace.json");
+  const current = readJson(target);
+  const alive = existingSessionIds(home);
+  const filterIds = (list) => (Array.isArray(list) ? list.filter((id) => typeof id === "string" && (alive.size === 0 || alive.has(id))) : []);
+  const incomingWorkspaces = incoming.tables?.workspaces !== null && typeof incoming.tables?.workspaces === "object" ? incoming.tables.workspaces : {};
+  const mergedWorkspaces = { ...(current?.tables?.workspaces ?? {}) };
+  for (const [id, workspace] of Object.entries(incomingWorkspaces)) {
+    if (workspace === null || typeof workspace !== "object") continue;
+    mergedWorkspaces[id] = {
+      ...workspace,
+      path: remapOriginPath(workspace.path, manifest.origin, home),
+      sessionIds: filterIds(workspace.sessionIds),
+    };
+  }
+  const currentGlobal = current?.global ?? {};
+  const incomingGlobal = incoming.global ?? {};
+  const workspaceIds = [];
+  for (const id of [...(currentGlobal.workspaceIds ?? []), ...(incomingGlobal.workspaceIds ?? []), ...Object.keys(mergedWorkspaces)]) {
+    if (typeof id === "string" && mergedWorkspaces[id] !== undefined && !workspaceIds.includes(id)) workspaceIds.push(id);
+  }
+  let defaultWorkspaceId = null;
+  if (typeof currentGlobal.defaultWorkspaceId === "string" && mergedWorkspaces[currentGlobal.defaultWorkspaceId] !== undefined) {
+    defaultWorkspaceId = currentGlobal.defaultWorkspaceId;
+  } else if (typeof incomingGlobal.defaultWorkspaceId === "string" && mergedWorkspaces[incomingGlobal.defaultWorkspaceId] !== undefined) {
+    defaultWorkspaceId = incomingGlobal.defaultWorkspaceId;
+  } else {
+    defaultWorkspaceId = workspaceIds[0] ?? null;
+  }
+  const unique = (values) => [...new Set(values)];
+  const merged = {
+    ...(current ?? {}),
+    unit: incoming.unit ?? current?.unit ?? { name: "workspace", version: 2 },
+    global: {
+      ...currentGlobal,
+      initialized: true,
+      defaultWorkspaceId,
+      workspaceIds,
+      archivedSessionIds: unique([...(currentGlobal.archivedSessionIds ?? []), ...filterIds(incomingGlobal.archivedSessionIds)]),
+      pinnedSessionIds: unique([...(currentGlobal.pinnedSessionIds ?? []), ...filterIds(incomingGlobal.pinnedSessionIds)]),
+    },
+    tables: {
+      ...(current?.tables ?? {}),
+      workspaces: mergedWorkspaces,
+    },
+  };
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+  return Object.keys(incomingWorkspaces).length;
+}
+
+/** Restore the optional workspace folders next to their (remapped) workspace paths. */
+function restoreWorkspaceFolders(home, entries, manifest, warnings) {
+  const groups = new Map();
+  for (const entry of entries) {
+    const relativePath = safeRelative(entry.path);
+    const match = relativePath.match(/^payload\/workspace-folders\/([^/]+)\/(.+)$/u);
+    if (match === null) continue;
+    const [, folderName, fileRelative] = match;
+    if (!groups.has(folderName)) groups.set(folderName, []);
+    groups.get(folderName).push({ data: entry.data, fileRelative });
+  }
+  if (groups.size === 0) return 0;
+  const registry = readJson(path.join(home, "storages", "workspace.json"));
+  const targets = new Map();
+  for (const [id, workspace] of Object.entries(registry?.tables?.workspaces ?? {})) {
+    if (typeof workspace?.path === "string" && workspace.path.length > 0) targets.set(workspaceFolderName(id), workspace.path);
+  }
+  for (const workspace of manifest.workspaceFolders ?? []) {
+    if (typeof workspace?.relative !== "string" || typeof workspace?.path !== "string") continue;
+    const folderName = workspace.relative.replace("payload/workspace-folders/", "");
+    if (!targets.has(folderName)) targets.set(folderName, remapOriginPath(workspace.path, manifest.origin, home));
+  }
+  const stamp = new Date().toISOString().replace(/[:.]/gu, "-").slice(0, 19);
+  let restored = 0;
+  for (const [folderName, files] of groups.entries()) {
+    const target = targets.get(folderName);
+    if (typeof target !== "string" || target.length === 0) {
+      warnings.push(`папка рабочей области ${folderName} пропущена: не найден целевой путь`);
+      continue;
+    }
+    let targetRoot = target;
+    let isEmpty = false;
+    try {
+      isEmpty = fs.statSync(targetRoot).isDirectory() && fs.readdirSync(targetRoot).length === 0;
+    } catch {
+      isEmpty = false;
+    }
+    if (!isEmpty && fs.existsSync(targetRoot)) {
+      targetRoot = `${target}-dsh-restored-${stamp}`;
+      warnings.push(`папка ${target} уже существует — восстановлено рядом: ${targetRoot}`);
+    }
+    for (const file of files) {
+      const resolved = path.resolve(targetRoot, file.fileRelative);
+      const rootResolved = path.resolve(targetRoot);
+      if (!resolved.startsWith(rootResolved + path.sep)) {
+        warnings.push(`пропущен небезопасный путь папки рабочей области: ${file.fileRelative}`);
+        continue;
+      }
+      try {
+        fs.mkdirSync(path.dirname(resolved), { recursive: true });
+        fs.writeFileSync(resolved, file.data);
+      } catch (error) {
+        warnings.push(`не удалось записать ${file.fileRelative}: ${String(error?.message ?? error)}`);
+      }
+    }
+    restored += 1;
+  }
+  return restored;
+}
+
+function backupCurrent(home, profileName, selection) {
+  const stamp = new Date().toISOString().replace(/[:.]/gu, "-").slice(0, 19);
+  const backupDir = path.join(home, `backup-import-${stamp}`);
+  fs.mkdirSync(backupDir, { recursive: true });
+  const copyInto = (source, relative) => {
+    if (!fs.existsSync(source)) return;
+    const target = path.join(backupDir, relative);
+    fs.cpSync(source, target, { recursive: true, filter: (item) => !EXCLUDED_NAMES.has(path.basename(item)) });
+  };
+  copyInto(path.join(home, "profiles", profileName), `profiles/${profileName}`);
+  if (selection.workspaces !== false) copyInto(path.join(home, "storages", "workspace.json"), "storages/workspace.json");
+  if (selection.skills !== false) copyInto(path.join(home, "skills"), "skills");
+  if (selection.memory !== false) copyInto(path.join(home, "memory"), "memory");
+  if (selection.projectsMemory !== false) copyInto(path.join(home, "projects-memory"), "projects-memory");
+  copyInto(path.join(home, "AGENTS.md"), "AGENTS.md");
+  return backupDir;
+}
+
+export function applyBundle(options = {}) {
+  const home = options.home ?? defaultHome();
+  const profileName = options.profile ?? "desktop";
+  const archivePath = options.archivePath;
+  if (typeof archivePath !== "string" || !fs.existsSync(archivePath)) throw new Error(`архив не найден: ${archivePath}`);
+  const inspected = inspectBundle(archivePath);
+  const selection = normalizeSelection(options.selection ?? inspected.manifest.selection);
+  const entries = parseTarGz(fs.readFileSync(archivePath));
+  const warnings = [];
+  const restored = { profile: 0, localPlugins: 0, workspaces: 0, workspaceFolders: 0, skills: 0, memory: 0, projectsMemory: 0, config: 0, sessions: 0, attachments: 0, credentials: 0 };
+  let backupDir;
+  if (options.backup !== false) backupDir = backupCurrent(home, profileName, selection);
+
+  const writeEntry = (relativePath, data) => {
+    const target = path.join(home, relativePath);
+    const resolved = path.resolve(target);
+    if (!resolved.startsWith(path.resolve(home) + path.sep)) throw new Error(`небезопасный путь распаковки: ${relativePath}`);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    fs.writeFileSync(resolved, data);
+  };
+
+  const skipSelection = (relativePath) => {
+    if (relativePath.startsWith("payload/workspaces/") && selection.workspaces === false) return true;
+    if (relativePath.startsWith("payload/workspace-folders/") && selection.workspaceFolders !== true) return true;
+    if (relativePath.startsWith("payload/skills/") && selection.skills === false) return true;
+    if (relativePath.startsWith("payload/memory/") && selection.memory === false) return true;
+    if (relativePath.startsWith("payload/projects-memory/") && selection.projectsMemory === false) return true;
+    if (relativePath.startsWith("payload/local-plugins/") && selection.localPlugins === false) return true;
+    if (relativePath.startsWith("payload/sessions/") && selection.sessions !== true) return true;
+    if (relativePath.startsWith("payload/attachments/") && selection.attachments !== true) return true;
+    if (relativePath.endsWith(".credentials.yaml") && selection.credentials !== true) return true;
+    return false;
+  };
+
+  const localPluginRoot = path.join(home, "local-plugins");
+  for (const entry of entries) {
+    if (entry.type !== "0" || entry.path === "manifest.json") continue;
+    const relativePath = safeRelative(entry.path);
+    if (skipSelection(relativePath)) continue;
+    if (relativePath.startsWith("payload/workspaces/")) continue;
+    if (relativePath.startsWith("payload/workspace-folders/")) continue;
+    if (relativePath === "01-INSTALL.cmd" || relativePath === "install-on-clean-machine.ps1" || relativePath === "README-INSTALL.md" || relativePath.startsWith("bootstrap-plugin/")) continue;
+    if (relativePath.startsWith("payload/dsh/")) {
+      const name = relativePath.slice("payload/dsh/".length);
+      if (name === ".credentials.yaml") {
+        writeEntry(path.join(".", name), entry.data);
+        restored.credentials += 1;
+      } else {
+        writeEntry(name, entry.data);
+        restored.config += 1;
+      }
+      continue;
+    }
+    if (relativePath.startsWith("payload/profiles/")) {
+      const name = relativePath.slice(`payload/profiles/${profileName}/`.length);
+      if (name === relativePath) continue;
+      writeEntry(path.join("profiles", profileName, name), entry.data);
+      restored.profile += 1;
+      continue;
+    }
+    if (relativePath.startsWith("payload/skills/")) {
+      writeEntry(path.join("skills", relativePath.slice("payload/skills/".length)), entry.data);
+      restored.skills += 1;
+      continue;
+    }
+    if (relativePath.startsWith("payload/memory/")) {
+      writeEntry(path.join("memory", relativePath.slice("payload/memory/".length)), entry.data);
+      restored.memory += 1;
+      continue;
+    }
+    if (relativePath.startsWith("payload/projects-memory/")) {
+      writeEntry(path.join("projects-memory", relativePath.slice("payload/projects-memory/".length)), entry.data);
+      restored.projectsMemory += 1;
+      continue;
+    }
+    if (relativePath.startsWith("payload/local-plugins/")) {
+      const rest = relativePath.slice("payload/local-plugins/".length);
+      const [packageName, ...segments] = rest.split("/");
+      if (!packageName || segments.length === 0) continue;
+      if (!isSafePackageName(packageName)) {
+        warnings.push(`пропущен небезопасный пакет: ${packageName}`);
+        continue;
+      }
+      writeEntry(path.join("local-plugins", packageName, ...segments), entry.data);
+      restored.localPlugins += 1;
+      continue;
+    }
+    if (relativePath.startsWith("payload/sessions/")) {
+      writeEntry(path.join("sessions", relativePath.slice("payload/sessions/".length)), entry.data);
+      restored.sessions += 1;
+      continue;
+    }
+    if (relativePath.startsWith("payload/attachments/")) {
+      writeEntry(path.join("attachments", relativePath.slice("payload/attachments/".length)), entry.data);
+      restored.attachments += 1;
+      continue;
+    }
+    warnings.push(`пропущен неизвестный путь: ${relativePath}`);
+  }
+
+  // Workspace registry: restore names, folder paths and chat grouping; merge
+  // with the local registry and drop references to sessions not present here.
+  const workspaceEntry = entries.find((entry) => entry.type === "0" && safeRelative(entry.path) === "payload/workspaces/workspace.json");
+  if (workspaceEntry !== undefined && selection.workspaces !== false) {
+    try {
+      restored.workspaces = restoreWorkspaceRegistry(home, JSON.parse(workspaceEntry.data.toString("utf8")), inspected.manifest);
+    } catch (error) {
+      warnings.push(`рабочие области не восстановлены: ${String(error?.message ?? error)}`);
+    }
+  }
+
+  // Optional workspace folders: restored next to their (remapped) workspace paths.
+  if (selection.workspaceFolders === true) {
+    const folderEntries = entries.filter((entry) => entry.type === "0" && safeRelative(entry.path).startsWith("payload/workspace-folders/"));
+    if (folderEntries.length > 0) {
+      try {
+        restored.workspaceFolders = restoreWorkspaceFolders(home, folderEntries, inspected.manifest, warnings);
+      } catch (error) {
+        warnings.push(`папки рабочих областей не восстановлены: ${String(error?.message ?? error)}`);
+      }
+    }
+  }
+
+  // Rewrite link: dependencies so they point to the restored local plugin folder.
+  let needsPnpm = false;
+  const profileJsonPath = path.join(home, "profiles", profileName, "package.json");
+  if (fs.existsSync(profileJsonPath) && restored.localPlugins > 0) {
+    const manifest = readJson(profileJsonPath);
+    if (manifest !== undefined && manifest.dependencies !== null && typeof manifest.dependencies === "object") {
+      let touched = false;
+      for (const plugin of inspected.manifest.localPlugins ?? []) {
+        if (!isSafePackageName(plugin.packageName)) {
+          warnings.push(`небезопасное имя пакета в манифесте: ${plugin.packageName}`);
+          continue;
+        }
+        const restoredDir = path.join(localPluginRoot, plugin.packageName);
+        if (!fs.existsSync(restoredDir)) continue;
+        const spec = `link:${restoredDir.replaceAll("\\", "/")}`;
+        if (manifest.dependencies[plugin.packageName] !== spec) {
+          manifest.dependencies[plugin.packageName] = spec;
+          touched = true;
+        }
+      }
+      if (touched) {
+        fs.writeFileSync(profileJsonPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+        needsPnpm = true;
+      }
+    }
+  }
+  const nodeModules = path.join(home, "profiles", profileName, "node_modules");
+  if (!fs.existsSync(nodeModules)) needsPnpm = true;
+
+  const summaryPath = path.join(home, "profile-transfer-last.json");
+  fs.writeFileSync(summaryPath, `${JSON.stringify({
+    appliedAt: new Date().toISOString(),
+    archive: archivePath,
+    manifest: { createdAt: inspected.manifest.createdAt, host: inspected.manifest.host, totals: inspected.manifest.totals },
+    selection,
+    restored,
+    backupDir,
+    needsPnpm,
+    warnings,
+  }, null, 2)}\n`, "utf8");
+
+  return { restored, backupDir, needsPnpm, warnings, summaryPath, manifest: inspected.manifest, selection };
+}
+
+/* ------------------------------------------------------------------ */
+/* small public helpers                                               */
+/* ------------------------------------------------------------------ */
+
+export { humanSize, profileDirectory, localPluginTargets, readJson, walkFiles };