dsh-desktop-kit 2.2.0 → 2.7.2

package/plugins/dsh-memory-bridge/lib/portable.js

@@ -0,0 +1,314 @@
+/**
+ * Portable project-memory export/import for a USB drive (or any local folder).
+ *
+ * The canonical payload is a plain folder:
+ *
+ *   <destination>/dsh-memory-portable/
+ *     manifest.json                  format, checksum, machine, projects
+ *     README.md                      human instructions
+ *     projects/<slug>--<key8>/*.md   redacted dossiers, no AUTO-SCAN blocks
+ *
+ * The manifest is the trust boundary: paths are validated, every file is
+ * SHA-256 checked, and import always backs up an existing local dossier first.
+ * No GitHub, network, credentials or LLM calls are involved.
+ */
+
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  BridgeError,
+  DEFAULT_LIMITS,
+  canonicalizePaths,
+  ensureDir,
+  exists,
+  isAllowedSyncPath,
+  redactSecrets,
+  safeRelPath,
+  sha256,
+  writeFileAtomic,
+  writeJsonAtomic,
+} from "./bridge.js";
+import { localFileText, syncText } from "./github.js";
+import * as st from "./state.js";
+
+export const PORTABLE_FORMAT = "dsh-memory-portable";
+export const PORTABLE_VERSION = 1;
+const FOLDER_NAME = "dsh-memory-portable";
+const MANIFEST_NAME = "manifest.json";
+const README_NAME = "README.md";
+const MAX_MANIFEST_BYTES = 2 * 1024 * 1024;
+
+function portableRoot(source) {
+  const raw = String(source ?? "").trim();
+  if (raw.length === 0) throw new BridgeError("portable/no-path", "укажите папку флешки, например E:\\");
+  const resolved = path.resolve(raw);
+  return path.basename(resolved).toLowerCase() === FOLDER_NAME ? resolved : path.join(resolved, FOLDER_NAME);
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value !== null && typeof value === "object") {
+    const result = {};
+    for (const key of Object.keys(value).sort()) result[key] = stableValue(value[key]);
+    return result;
+  }
+  return value;
+}
+
+function manifestChecksum(payload) {
+  return sha256(JSON.stringify(stableValue(payload)));
+}
+
+function slugSafe(value, label) {
+  const slug = String(value ?? "").trim();
+  if (!/^[a-z0-9][a-z0-9._-]{0,79}$/u.test(slug)) throw new BridgeError("portable/bad-manifest", `${label}: некорректный slug`);
+  return slug;
+}
+
+function folderSafe(value) {
+  const folder = String(value ?? "").trim();
+  if (folder.length === 0 || folder.includes("/") || folder.includes("\\") || folder === "." || folder === "..") {
+    throw new BridgeError("portable/bad-manifest", "некорректная папка проекта в манифесте");
+  }
+  safeRelPath(folder);
+  return folder;
+}
+
+function projectFolder(target) {
+  const slug = String(target.slug ?? "project").replace(/[^A-Za-z0-9._-]+/gu, "-").slice(0, 40) || "project";
+  return `${slug}--${String(target.projectKey ?? "").slice(0, 8)}`;
+}
+
+async function readManifest(root) {
+  const file = path.join(root, MANIFEST_NAME);
+  let stat;
+  try {
+    stat = await fsp.stat(file);
+  } catch {
+    throw new BridgeError("portable/no-manifest", "на флешке нет dsh-memory-portable/manifest.json — сначала сохраните проекты из плагина");
+  }
+  if (!stat.isFile() || stat.size > MAX_MANIFEST_BYTES) throw new BridgeError("portable/bad-manifest", "manifest.json слишком большой или не файл");
+  let manifest;
+  try {
+    manifest = JSON.parse(await fsp.readFile(file, "utf8"));
+  } catch {
+    throw new BridgeError("portable/bad-manifest", "manifest.json повреждён (не JSON)");
+  }
+  if (manifest === null || typeof manifest !== "object" || manifest.format !== PORTABLE_FORMAT) {
+    throw new BridgeError("portable/bad-manifest", "это не переносимый каталог памяти DSH");
+  }
+  if (manifest.version !== PORTABLE_VERSION) {
+    throw new BridgeError("portable/bad-version", `версия формата ${String(manifest.version)} не поддерживается (ожидается ${PORTABLE_VERSION})`);
+  }
+  if (!Array.isArray(manifest.projects)) throw new BridgeError("portable/bad-manifest", "в манифесте нет списка проектов");
+  const expected = manifestChecksum({ ...manifest, checksum: undefined });
+  if (manifest.checksum !== expected) throw new BridgeError("portable/tampered", "контрольная сумма манифеста не совпадает — флешка изменена");
+  return manifest;
+}
+
+async function readPortableFile(projectDir, relativePath) {
+  const safe = safeRelPath(relativePath);
+  const file = path.join(projectDir, ...String(safe).split("/"));
+  let stat;
+  try {
+    stat = await fsp.stat(file);
+  } catch {
+    throw new BridgeError("portable/missing-file", `на флешке нет файла ${relativePath}`);
+  }
+  if (!stat.isFile() || stat.size > DEFAULT_LIMITS.maxFileBytes) {
+    throw new BridgeError("portable/bad-file", `файл ${relativePath} слишком большой или не файл`);
+  }
+  return fsp.readFile(file, "utf8");
+}
+
+async function localCanonicalFiles(directory, home) {
+  const raw = await st.readLocalDossier(directory, {
+    maxFileBytes: DEFAULT_LIMITS.maxFileBytes,
+    maxBundleBytes: DEFAULT_LIMITS.maxBundleBytes,
+    maxFiles: DEFAULT_LIMITS.maxFiles,
+  });
+  const map = new Map();
+  for (const [relativePath, text] of raw.raw) {
+    if (!isAllowedSyncPath(relativePath)) continue;
+    const canonical = redactSecrets(canonicalizePaths(syncText(relativePath, text), home)).trimEnd();
+    if (canonical.length > 0) map.set(relativePath, canonical);
+  }
+  return map;
+}
+
+/**
+ * Export every locally registered project dossier into a portable folder.
+ * @returns {Promise<{root:string, projects:Array, files:number, bytes:number}>}
+ */
+export async function exportPortable({ home, destination, targets, machine }) {
+  const root = portableRoot(destination);
+  await ensureDir(root);
+  await ensureDir(path.join(root, "projects"));
+  const projects = [];
+  let filesCount = 0;
+  let bytes = 0;
+  for (const target of targets) {
+    const files = await localCanonicalFiles(target.directory, home);
+    if (files.size === 0) continue;
+    const folder = projectFolder(target);
+    const projectDir = path.join(root, "projects", folder);
+    await ensureDir(projectDir);
+    const entries = [];
+    for (const [relativePath, canonical] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
+      safeRelPath(relativePath);
+      if (!isAllowedSyncPath(relativePath)) continue;
+      const portableText = canonical.trimEnd();
+      if (portableText.length === 0) continue;
+      const targetFile = path.join(projectDir, ...relativePath.split("/"));
+      await writeFileAtomic(targetFile, `${portableText}\n`);
+      entries.push({ path: relativePath, bytes: Buffer.byteLength(portableText, "utf8"), sha256: sha256(portableText) });
+      filesCount += 1;
+      bytes += Buffer.byteLength(portableText, "utf8");
+    }
+    if (entries.length > 0) {
+      projects.push({
+        slug: target.slug,
+        name: target.name,
+        folder,
+        projectKey: target.projectKey,
+        files: entries,
+      });
+    }
+  }
+  const createdAt = new Date().toISOString();
+  const payload = {
+    format: PORTABLE_FORMAT,
+    version: PORTABLE_VERSION,
+    createdAt,
+    machine: machine ? { label: String(machine.label ?? ""), id: String(machine.machineId ?? machine.id ?? "") } : null,
+    projects,
+    checksum: "",
+  };
+  payload.checksum = manifestChecksum({ ...payload, checksum: undefined });
+  await writeJsonAtomic(path.join(root, MANIFEST_NAME), payload, { mode: 0o600 });
+  await writeFileAtomic(
+    path.join(root, README_NAME),
+    [
+      "# dsh-memory-portable",
+      "",
+      "Перенос памяти проектов DeepSeek Harness через флешку.",
+      "",
+      "## Как восстановить на другой машине",
+      "",
+      "1. Подключите флешку к компьютеру.",
+      "2. Откройте DSH → Настройки → «Память проектов» → раздел «Флешка».",
+      "3. Укажите путь к флешке (например, `E:\\`) и нажмите «Сканировать».",
+      "4. Проверьте список проектов и нажмите «Импортировать».",
+      "",
+      "Плагин сохранит текущие досье в бэкап и восстановит память проектов.",
+      "Секреты и PII вычищаются при экспорте; AUTO-SCAN-блоки не переносятся.",
+      "",
+      `Формат: ${PORTABLE_FORMAT} v${PORTABLE_VERSION}`,
+      "",
+    ].join("\n"),
+    { mode: 0o600 },
+  );
+  return { root, createdAt, projects, files: filesCount, bytes };
+}
+
+/**
+ * Validate a portable folder and compare it with local dossiers.
+ * @returns {Promise<{root:string, manifest:object, projects:Array}>}
+ */
+export async function scanPortable({ home, source, targets }) {
+  const root = portableRoot(source);
+  if (!(await exists(root))) throw new BridgeError("portable/no-folder", `папка не найдена: ${root}`);
+  const manifest = await readManifest(root);
+  const localBySlug = new Map(targets.map((target) => [target.slug, target]));
+  const projects = [];
+  for (const entry of manifest.projects) {
+    if (entry === null || typeof entry !== "object") throw new BridgeError("portable/bad-manifest", "некорректная запись проекта");
+    const slug = slugSafe(entry.slug, "project");
+    const folder = folderSafe(entry.folder);
+    if (!Array.isArray(entry.files) || entry.files.length === 0) throw new BridgeError("portable/bad-manifest", `${slug}: no files`);
+    let same = false;
+    for (const file of entry.files) {
+      if (file === null || typeof file !== "object") throw new BridgeError("portable/bad-manifest", `${slug}: bad file entry`);
+      const relativePath = safeRelPath(file.path);
+      if (!isAllowedSyncPath(relativePath)) throw new BridgeError("portable/bad-manifest", `${slug}: path not allowed`);
+      const text = await readPortableFile(path.join(root, "projects", folder), relativePath);
+      const canonical = text.replace(/\r\n/gu, "\n").trimEnd();
+      if (sha256(canonical) !== file.sha256) throw new BridgeError("portable/tampered", `${slug}/${relativePath}: контрольная сумма файла не совпадает`);
+      if (Number(file.bytes) !== Buffer.byteLength(canonical, "utf8")) throw new BridgeError("portable/tampered", `${slug}/${relativePath}: размер файла не совпадает`);
+    }
+    const target = localBySlug.get(slug) ?? null;
+    if (target) {
+      const local = await localCanonicalFiles(target.directory, home);
+      same = local.size === entry.files.length;
+      if (same) {
+        for (const file of entry.files) {
+          if (local.get(file.path) === undefined || sha256(local.get(file.path)) !== file.sha256) {
+            same = false;
+            break;
+          }
+        }
+      }
+    }
+    projects.push({
+      slug,
+      name: typeof entry.name === "string" && entry.name.length > 0 ? entry.name : slug,
+      folder,
+      files: entry.files.length,
+      status: target === null ? "new" : same ? "same" : "update",
+    });
+  }
+  return { root, createdAt: manifest.createdAt ?? null, machine: manifest.machine ?? null, projects };
+}
+
+/**
+ * Import selected projects from a portable folder into local dossiers.
+ * Default strategy rewrites the dossier, but always backs up an existing one first.
+ * @returns {Promise<{root:string, imported:number, skipped:number, projects:Array}>}
+ */
+export async function importPortable({ home, source, targets, projectSlugs, strategy = "replace" }) {
+  const root = portableRoot(source);
+  const manifest = await readManifest(root);
+  const selected = Array.isArray(projectSlugs) && projectSlugs.length > 0 ? new Set(projectSlugs.map(String)) : null;
+  const localBySlug = new Map(targets.map((target) => [target.slug, target]));
+  const projects = [];
+  let imported = 0;
+  let skipped = 0;
+  for (const entry of manifest.projects) {
+    const slug = slugSafe(entry.slug, "project");
+    if (selected !== null && !selected.has(slug)) continue;
+    const folder = folderSafe(entry.folder);
+    if (!Array.isArray(entry.files) || entry.files.length === 0) continue;
+    const target = localBySlug.get(slug) ?? null;
+    const directory = target?.directory ?? path.join(st.pathsFor(home).projectsMemory, slug);
+    const current = await st.readLocalDossier(directory, {
+      maxFileBytes: DEFAULT_LIMITS.maxFileBytes,
+      maxBundleBytes: DEFAULT_LIMITS.maxBundleBytes,
+      maxFiles: DEFAULT_LIMITS.maxFiles,
+    });
+    if (strategy === "skip" && current.raw.size > 0) {
+      skipped += 1;
+      projects.push({ slug, status: "skipped", files: entry.files.length });
+      continue;
+    }
+    if (current.raw.size > 0) {
+      await st.backupDossier(home, slug, directory, { maxFileBytes: DEFAULT_LIMITS.maxFileBytes });
+    }
+    await ensureDir(directory);
+    let written = 0;
+    for (const file of entry.files) {
+      const relativePath = safeRelPath(file.path);
+      if (!isAllowedSyncPath(relativePath)) continue;
+      const text = await readPortableFile(path.join(root, "projects", folder), relativePath);
+      const canonical = text.replace(/\r\n/gu, "\n").trimEnd();
+      if (sha256(canonical) !== file.sha256) throw new BridgeError("portable/tampered", `${slug}/${relativePath}: файл изменён после сканирования`);
+      const next = localFileText(relativePath, canonical, current.raw.get(relativePath) ?? "");
+      await writeFileAtomic(path.join(directory, ...relativePath.split("/")), next);
+      written += 1;
+    }
+    imported += 1;
+    projects.push({ slug, status: target === null ? "imported-new" : "imported", files: written });
+  }
+  return { root, imported, skipped, projects };
+}