dsh-config-manager 0.1.76 → 0.1.78

package/src/adapters/plugins.ts

@@ -13,7 +13,7 @@
 import { join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { sha256Hex } from '../utils/hashing.ts';
-import { installSpecFor, resolveProcessProfileName } from '../core/plugin-cli.ts';
+import { installSpecFor, isBundlesOnlyEntry, mergeBundleDeclaration, resolveProcessProfileName } from '../core/plugin-cli.ts';
 import { classifyPluginSpec, LOCAL_PLUGIN_DIR, resolveLocalPluginPath } from '../core/local-plugin-pack.ts';
 import type { PackLocalPluginsResult } from '../core/local-plugin-pack.ts';
 import { msgOf, zhMsg } from '../core/messages.ts';
@@ -22,14 +22,17 @@ import { engineMsg } from './messages.ts';
 import { stringifyJsonSafe } from '../utils/json.ts';
 import { isPathSafe, normalizePath } from '../utils/paths.ts';
 import { isENOENT } from '../utils/guards.ts';
-import { PLUGIN_PATCH_REF_PREFIX } from '../core/backup.ts';
+import { PLUGIN_PATCH_REF_PREFIX, PLUGIN_PROFILE_MANIFEST_REF } from '../core/backup.ts';
 import { readEffectivePatchLines, resolveWriteLayer, USER_PATCH_FILE } from '../core/patch-layers.ts';
 import { parsePnpmPatchedDependencies, sanitizePnpmWorkspacePatches } from './pnpm-workspace.ts';
 import type { LocalPluginTarball, PatchLine, PluginEntry, PluginsSection, PnpmPatchFile } from '../schema/types.ts';
 import type {
   ApplyResult, ConfigAdapter, ExportOptions, ExportSection, ExportUnit, HostContext,
-  ImportContext, PlanItem, SectionPreview, ValidationResult,
+  ImportContext, PlanItem, PluginAreaRef, SectionPreview, ValidationResult,
 } from '../core/types.ts';
+import { BUILTIN_PLUGIN_DATA_SOURCES, areasForSection } from '../core/plugin-data-registry.ts';
+import type { PluginDataSource } from '../core/plugin-data-registry.ts';
+import { declaredProfileName, scanDeclaredDataSources } from './plugin-data-declared.ts';
 import { sectionMeta } from '../schema/section-registry.ts';
 import { validateJsonSection } from './json-section.ts';
 
@@ -156,6 +159,68 @@ function entriesOfRaw(raw: unknown): { config?: unknown }[] {
  */
 const previewTarballBytes = new WeakMap<object, Map<string, number>>();
 
+/**
+ * 「插件包名 → 它声明的数据区域」映射（只有 \`plugin:<包名>\` 单元用；导出选择器「按插件看」的树骨架）。
+ *
+ * 为什么挂 WeakMap 而不是给 PluginsSection 加字段：这是**展示用旁路信息** —— 既不是备份格式的
+ * 一部分（schema 校验与市场防线都不该看见它），也与「导出真的带什么」无关；挂在载荷对象上随对象
+ * 一起回收，载荷本身逐字节不变（与 previewTarballBytes 同一套理由）。
+ */
+const relatedAreasByData = new WeakMap<object, Map<string, PluginAreaRef[]>>();
+
+/** 内置来源 + 自述声明的扫描缓存（TTL 内的同一 home/profile 只扫一次；/export-preview 一趟会问两次） */
+const declaredSourcesMemo: { key: string; at: number; sources: readonly PluginDataSource[] } =
+  { key: '', at: 0, sources: [] };
+const DECLARED_MEMO_TTL_MS = 5_000;
+
+/**
+ * 本机可归属的插件数据来源 = 内置来源表 + 已安装插件自述声明。
+ *
+ * 缓存键必须带 homeDir + profile：同一台机器换 profile 就是另一批已安装插件，拿旧声明画树
+ * 会让用户看到不属于当前 profile 的数据区域。
+ */
+async function pluginDataSources(ctx: HostContext): Promise<readonly PluginDataSource[]> {
+  const key = ctx.homeDir + '|' + declaredProfileName(ctx.profile);
+  const now = Date.now();
+  if (declaredSourcesMemo.key === key && now - declaredSourcesMemo.at < DECLARED_MEMO_TTL_MS) {
+    return declaredSourcesMemo.sources;
+  }
+  const sources = [...BUILTIN_PLUGIN_DATA_SOURCES, ...await scanDeclaredDataSources(ctx)];
+  declaredSourcesMemo.key = key;
+  declaredSourcesMemo.at = now;
+  declaredSourcesMemo.sources = sources;
+  return sources;
+}
+
+/**
+ * 包名 → 该插件的数据区域引用。
+ *
+ * 口径与 pluginData / pluginAssets 的收集面**同源**（同一个 areasForSection）：role=config 进
+ * pluginData、role=assets 进 pluginAssets；role=cache 的区域不属于任何分区，因此**绝不进树**
+ * （缓存是可再生产物，列出来只会诱导用户把它带走）。
+ *
+ * 只产出「注册表说它应该在哪儿」，不代表磁盘上真有 —— 界面必须把两者分开渲染。
+ */
+async function relatedAreasOf(ctx: HostContext): Promise<Map<string, PluginAreaRef[]>> {
+  const sources = await pluginDataSources(ctx);
+  const map = new Map<string, PluginAreaRef[]>();
+  for (const source of sources) {
+    const refs: PluginAreaRef[] = [];
+    for (const section of ['pluginData', 'pluginAssets'] as const) {
+      for (const entry of areasForSection([source], section)) {
+        refs.push({ section, relPath: entry.area.relPath, role: entry.area.role === 'assets' ? 'assets' : 'config' });
+      }
+    }
+    if (refs.length === 0) continue;
+    for (const pkg of source.packages) {
+      const cur = map.get(pkg);
+      if (cur === undefined) map.set(pkg, [...refs]);
+      else cur.push(...refs);
+    }
+  }
+  return map;
+}
+
 /**
  * 零 spawn 推导本地源插件的体积（预览专用）。
  *
@@ -208,7 +273,11 @@ async function measureLocalSources(plugins: PluginEntry[], ctx: HostContext): Pr
  * `tarballBytes` = 预览路径登记到的本地源体积（见 measureLocalSources，0 = 体积未知但仍随包携带）；
  * 缺省时体积与文件数完全按导出产物里的 base64 计算 —— 与改造前逐字一致。
  */
-function unitsOf(data: PluginsSection, tarballBytes?: Map<string, number>): ExportUnit[] {
+function unitsOf(
+  data: PluginsSection,
+  tarballBytes?: Map<string, number>,
+  related?: Map<string, PluginAreaRef[]>,
+): ExportUnit[] {
   const wsId = 'plugins:pnpm-workspace';
   const patchFileIds = (data.patchFiles ?? []).map((pf) => `plugins:patch:${normalizePath(pf.relativePath)}`);
   const group = [wsId, ...patchFileIds];
@@ -216,6 +285,7 @@ function unitsOf(data: PluginsSection, tarballBytes?: Map<string, number>): Expo
   for (const pl of data.plugins) {
     const tarball = tarballOf(data, pl.name);
     const measured = tarballBytes?.get(pl.name);
+    const areas = related?.get(pl.name);
     units.push({
       id: `plugin:${pl.name}`,
       label: pl.name,
@@ -223,6 +293,8 @@ function unitsOf(data: PluginsSection, tarballBytes?: Map<string, number>): Expo
       // base64 长度 → 原始字节数（仅用于展示体积，不求精确）；预览路径没有字节，用 stat 量到的源体积
       sizeBytes: tarball !== undefined ? Math.floor((tarball.base64.length * 3) / 4) : measured ?? 0,
       ...(tarball !== undefined || measured !== undefined ? { fileCount: 1 } : {}),
+      // 「按插件看」的树骨架：该插件声明的数据区域（零数据目录 I/O）
+      ...(areas !== undefined && areas.length > 0 ? { relatedAreas: areas } : {}),
     });
   }
   for (const line of data.patch) {
@@ -249,6 +321,17 @@ function unitsOf(data: PluginsSection, tarballBytes?: Map<string, number>): Expo
   return units;
 }
 
+/**
+ * 目标机 profile 的 `dsh.profile.bundles` 视图（issue #95）。
+ *
+ * 三态**必须分开**：`absent`（没有 package.json）、`unreadable`（读失败 / JSON 坏 / 形状不符）、
+ * `ok`。把后两者当成「没有」会直接去写一份清单，抹掉 profile 的其它字段。
+ */
+type TargetBundleView =
+  | { state: 'ok'; names: Set<string>; text: string }
+  | { state: 'absent' }
+  | { state: 'unreadable'; reason: string };
+
 export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
   readonly id = 'plugins' as const;
   // 元数据唯一来源 = 注册表（t31）：不再与 ui/export-flow.ts 的导出目录各写一份
@@ -291,7 +374,7 @@ export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
       section: collected,
       // 与 src/index.ts 对 JSON 分区现算体积的口径一致（utf8 字节数）
       sizeBytes: new TextEncoder().encode(stringifyJsonSafe(data)).length,
-      items: unitsOf(data, tarballBytes),
+      items: unitsOf(data, tarballBytes, relatedAreasByData.get(data)),
     };
   }
 
@@ -317,6 +400,9 @@ export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
           isBundle: p.isBundle ?? false,
           inBundles: p.inBundles ?? [],
           enabled: p.enabled,
+          // issue #95：只在 dsh.profile.bundles 里声明的层（源机无依赖声明）必须带上这个标记，
+          // 导入端据此走「只声明」而不是 npm 安装。缺省不写，普通依赖的字节与改造前逐字一致。
+          ...(p.bundlesOnly === true ? { bundlesOnly: true } : {}),
         });
       }
     } catch (err) {
@@ -432,16 +518,28 @@ export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
       const alive = new Set(keptPlugins.map((pl) => pl.name));
       keptTarballs = localTarballs?.filter((t) => alive.has(t.packageName));
     }
+    const data: PluginsSection = {
+      version: 1,
+      plugins: keptPlugins,
+      patch: keptPatch,
+      pnpmWorkspace: keptWorkspace,
+      ...(keptTarballs !== undefined ? { localTarballs: keptTarballs } : {}),
+      ...(keptPatchFiles !== undefined ? { patchFiles: keptPatchFiles } : {}),
+    };
+    /**
+     * 「按插件看」的树骨架（导出选择器）：登记每个插件声明的数据区域。
+     * 只登记「至少有一个区域」的插件 —— 其余插件单元保持无该字段，界面据此不显示空壳节点。
+     * 归属信息是**附加**信息：扫描失败不得影响导出/预览本身（与 pluginData 同一纪律）。
+     */
+    try {
+      const related = await relatedAreasOf(ctx);
+      if (related.size > 0) relatedAreasByData.set(data, related);
+    } catch {
+      // 读不到声明就不登记（界面按「没有已知关联」渲染，绝不猜）
+    }
     return {
       sectionId: 'plugins',
-      data: {
-        version: 1,
-        plugins: keptPlugins,
-        patch: keptPatch,
-        pnpmWorkspace: keptWorkspace,
-        ...(keptTarballs !== undefined ? { localTarballs: keptTarballs } : {}),
-        ...(keptPatchFiles !== undefined ? { patchFiles: keptPatchFiles } : {}),
-      },
+      data,
       counts: {
         plugins: keptPlugins.length,
         patchLines: keptPatch.length,
@@ -461,8 +559,9 @@ export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
    * 由选择模型保证勾选/取消同步。
    */
   listUnits(section: ExportSection<PluginsSection>): ExportUnit[] {
-    // 预览产物没有 tarball 字节，体积来自 measureLocalSources 挂上的统计（导出产物走 base64 分支）
-    return unitsOf(section.data, previewTarballBytes.get(section.data));
+    // 预览产物没有 tarball 字节，体积来自 measureLocalSources 挂上的统计（导出产物走 base64 分支）；
+    // 「按插件看」的数据区域骨架同样由 collect() 登记在载荷对象上（两条路径逐字一致，units.test 钉住）
+    return unitsOf(section.data, previewTarballBytes.get(section.data), relatedAreasByData.get(section.data));
   }
 
   /**
@@ -492,6 +591,81 @@ export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
     return set;
   }
 
+  /**
+   * 读目标机 profile 的 `dsh.profile.bundles`（issue #95）。
+   *
+   * 相对路径与写入目标同源（`profiles/<profile>/package.json`），走 `ctx.target.fs` 而不是
+   * 宿主私有通道：与 pnpm-workspace.yaml / patch 文件同一条 I/O 纪律（受限、可被 MemFs 测试）。
+   */
+  private async targetBundles(ctx: ImportContext): Promise<TargetBundleView> {
+    const rel = `${PNPM_PROFILE_DIR(ctx.target.profile)}/package.json`;
+    try {
+      if (!(await ctx.target.fs.exists(rel))) return { state: 'absent' };
+      const text = new TextDecoder().decode(await ctx.target.fs.readFile(rel));
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        return { state: 'unreadable', reason: ctx.msg('adapter.pluginHostBundleBadJson') };
+      }
+      const bundles = (parsed as { dsh?: { profile?: { bundles?: unknown } } } | null)?.dsh?.profile?.bundles;
+      if (!Array.isArray(bundles) || bundles.some((entry) => typeof entry !== 'string')) {
+        return { state: 'unreadable', reason: ctx.msg('adapter.pluginHostBundleBadShape') };
+      }
+      return { state: 'ok', names: new Set(bundles as string[]), text };
+    } catch (err) {
+      return { state: 'unreadable', reason: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  /**
+   * 把 host 自带的层声明进目标机 profile 的 `dsh.profile.bundles`（issue #95）。
+   *
+   * 为什么**不走安装通道**：这类层的包由 DSH 从自己的安装位置解析；按裸包名 `dsh plugin add`
+   * 会把 npm `dist-tags.latest` 的副本装进 profile，与 host 的版本线脱节 —— 真机故障：
+   * host 0.2.1-rc.2 + 包 0.2.1-alpha.2 的隔离组契约对不上 → `session-controller` 一直 pending
+   * → 新建会话 service-unavailable。声明不了时只报非致命 warning（§34.17），不拖垮其余配置。
+   */
+  private async declareHostBundle(name: string, ctx: ImportContext): Promise<ApplyResult> {
+    const msg = ctx.msg;
+    const rel = `${PNPM_PROFILE_DIR(ctx.target.profile)}/package.json`;
+    const view = await this.targetBundles(ctx);
+    if (view.state === 'absent') {
+      return { ok: false, warning: true, message: msg('adapter.pluginHostBundleNoManifest', { name }) };
+    }
+    if (view.state === 'unreadable') {
+      return {
+        ok: false,
+        warning: true,
+        message: msg('adapter.pluginHostBundleManifestUnreadable', { name, reason: view.reason }),
+      };
+    }
+    if (view.names.has(name)) {
+      return { ok: true, needsRestart: false, message: msg('adapter.pluginHostBundleSame', { name }) };
+    }
+    const merged = mergeBundleDeclaration(view.text, name);
+    if (merged === null) {
+      return {
+        ok: false,
+        warning: true,
+        message: msg('adapter.pluginHostBundleManifestUnreadable', {
+          name,
+          reason: msg('adapter.pluginHostBundleBadShape'),
+        }),
+      };
+    }
+    try {
+      await ctx.target.fs.writeFile(rel, new TextEncoder().encode(merged.text));
+    } catch (err) {
+      return {
+        ok: false,
+        warning: true,
+        message: msg('adapter.pluginHostBundleWriteFailed', { name, reason: err instanceof Error ? err.message : String(err) }),
+      };
+    }
+    return { ok: true, needsRestart: true, message: msg('adapter.pluginHostBundleDeclared', { name }) };
+  }
+
   async analyzeImport(data: PluginsSection, ctx: ImportContext): Promise<PlanItem[]> {
     const msg = ctx.msg;
     const items: PlanItem[] = [];
@@ -582,8 +756,42 @@ export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
 
     // 插件：包名唯一键；同版本 Skip / 未装 Install / 版本不同 Conflict
     const targetInstalled = await ctx.target.plugins.listInstalled();
+    // issue #95：只在 dsh.profile.bundles 里声明的层（源机没有依赖声明）**不装 npm 包** ——
+    // 它的名字只声明进目标机的 bundles，由 DSH 从自己的安装位置解析。只在真出现这类条目时才读
+    // 目标清单（其余场景零额外 I/O，行为与改造前逐字一致）。
+    const bundleView = data.plugins.some((p) => isBundlesOnlyEntry(p)) ? await this.targetBundles(ctx) : null;
     for (const p of data.plugins) {
       const id = `plugin:${p.name}`;
+      if (isBundlesOnlyEntry(p)) {
+        if (bundleView !== null && bundleView.state === 'ok' && bundleView.names.has(p.name)) {
+          items.push({
+            id, kind: 'Skip', adapter: 'plugins',
+            description: msg('adapter.pluginHostBundleSame', { name: p.name }),
+            detail: msg('adapter.pluginHostBundleDetail'),
+            severity: 'info',
+          });
+        } else if (bundleView !== null && bundleView.state === 'ok') {
+          items.push({
+            id, kind: 'Create', adapter: 'plugins',
+            description: msg('adapter.pluginHostBundleDeclare', { name: p.name }),
+            detail: msg('adapter.pluginHostBundleDetail'),
+            severity: 'info',
+            target: { adapter: 'plugins', ref: PLUGIN_PROFILE_MANIFEST_REF },
+          });
+        } else {
+          // 清单缺 / 读不到 / 形态不符：**不猜也不重建**，如实告警（非致命，其余分区照常导入）
+          items.push({
+            id,
+            kind: 'Warning',
+            adapter: 'plugins',
+            description: bundleView === null || bundleView.state === 'absent'
+              ? msg('adapter.pluginHostBundleNoManifest', { name: p.name })
+              : msg('adapter.pluginHostBundleManifestUnreadable', { name: p.name, reason: bundleView.reason }),
+            severity: 'warning',
+          });
+        }
+        continue;
+      }
       const tp = targetInstalled.find((t) => t.name === p.name);
       // T1：该插件在备份内自带 tarball（本地源 link:/file:）→ 目标机无需原始路径即可安装。
       const hasTarball = tarballOf(data, p.name) !== undefined;
@@ -717,10 +925,16 @@ export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
     // 拖垮已成功导入的其余配置——与 workspaces 的「目标不可达 → warning」同款语义。
     if (item.id.startsWith('plugin:')) {
       const name = item.id.replace(/^plugin:/, '');
+      const data = ctx.sections.get('plugins') as PluginsSection | undefined;
+      // issue #95：host 自带的层（源机只在 dsh.profile.bundles 声明、没有依赖声明）走「只声明」，
+      // 绝不进 npm 安装通道（按裸包名装 = 把 dist-tag latest 的副本塞进 profile）。
+      const entry = data?.plugins.find((p) => p.name === name);
+      if (entry !== undefined && isBundlesOnlyEntry(entry)) {
+        return await this.declareHostBundle(name, ctx);
+      }
       try {
         // 非 registry 来源（github:/file: 等）按来源 spec 安装，registry 包按裸包名装 npm 最新版
-        const data = ctx.sections.get('plugins') as PluginsSection | undefined;
-        let spec = data?.plugins.find((p) => p.name === name)?.spec;
+        let spec = entry?.spec;
 
         // T1：备份内自带 tarball → 解包到 homeDir 内的本地插件缓存目录，把 spec 重写为绝对路径。
         // 这是「换机后本地插件不再丢失」的关键：原始绝对路径在目标机不存在，解包出的 tgz 一定存在。
@@ -796,6 +1010,11 @@ export class PluginsAdapter implements ConfigAdapter<PluginsSection> {
           if (typeof name !== 'string' || name === '') {
             issues.push({ path: `plugins[${i}].name`, message: msg('adapter.validate.requiredField', { subject: 'plugins[].name' }), severity: 'error' });
           }
+          // issue #95：`bundlesOnly` 决定走不走 npm 安装通道，写错类型必须拦下（缺省合法）
+          const bundlesOnly = (p as { bundlesOnly?: unknown }).bundlesOnly;
+          if (bundlesOnly !== undefined && typeof bundlesOnly !== 'boolean') {
+            issues.push({ path: `plugins[${i}].bundlesOnly`, message: msg('adapter.validate.boolean', { subject: 'plugins[].bundlesOnly' }), severity: 'error' });
+          }
         }
       }
       if (section.patch !== undefined && !Array.isArray(section.patch)) {

package/src/adapters/units.test.ts

@@ -147,6 +147,32 @@ test('plugins：按包名过滤，cordis 补丁行独立成单元', async () =>
   assert.deepEqual(filtered.data.patch, [], '未勾选的补丁行不得被带出');
 });
 
+test('plugins：「按插件看」的树骨架 —— 单元带上它声明的数据区域（内置来源表，缓存永不进树）', async () => {
+  const ctx = makeContext('win32', HOME);
+  // 内置来源表：dsh-mnemon → runtime(config) + data/documents(assets)；
+  // dsh-plugin-wallpaper-engine → 数据目录(config) + uploads(assets) + cache(**不属于任何分区**)
+  ctx.plugins.installed.set('dsh-mnemon', { name: 'dsh-mnemon', version: '1.0.0', enabled: true });
+  ctx.plugins.installed.set('dsh-plugin-wallpaper-engine', {
+    name: 'dsh-plugin-wallpaper-engine', version: '1.0.0', enabled: true,
+  });
+  ctx.plugins.installed.set('pkg-a', { name: 'pkg-a', version: '1.0.0', enabled: true });
+  const adapter = new PluginsAdapter();
+
+  const previewed = await adapter.preview(ctx, { includeSecrets: false });
+  assert.deepEqual(previewed.items.find((u) => u.id === 'plugin:dsh-mnemon')?.relatedAreas, [
+    { section: 'pluginData', relPath: '.mnemon/runtime', role: 'config' },
+    { section: 'pluginAssets', relPath: '.mnemon/data', role: 'assets' },
+    { section: 'pluginAssets', relPath: '.mnemon/documents', role: 'assets' },
+  ]);
+  const we = previewed.items.find((u) => u.id === 'plugin:dsh-plugin-wallpaper-engine')?.relatedAreas ?? [];
+  assert.deepEqual(we.map((r) => r.relPath), ['.dsh-wallpaper-engine', '.dsh-wallpaper-engine/uploads'],
+    'cache 区域可再生产物、不属于任何分区，绝不进树');
+  // 没有声明的插件不得凭空带上区域（不猜）
+  assert.equal(previewed.items.find((u) => u.id === 'plugin:pkg-a')?.relatedAreas, undefined);
+  // 预览与导出两条路径的单元清单必须逐项相同（本文件既有纪律）
+  assert.deepEqual(previewed.items, adapter.listUnits(previewed.section));
+});
+
 test('plugins：pnpm-workspace.yaml ↔ patch 文件是原子组（lockedWith 双向声明）', () => {
   const adapter = new PluginsAdapter();
   const section: ExportSection<PluginsSection> = {