@logictan/dsh-config-manager 0.1.60

package/src/schema/config.ts

@@ -0,0 +1,165 @@
+/**
+ * 各分区数据结构：ZIP 内 JSON 分区文件 → 解析/校验，以及分区文件路径表。
+ * 类型本体在 types.ts；本文件是「分区数据如何落盘/读回」的唯一出口。
+ */
+import { parseJsonSafe } from '../utils/json.ts';
+import { isPathSafe } from '../utils/paths.ts';
+import type {
+  CredentialsSection, FilesSection, McpSection, PluginsSection,
+  PromptsSection, ProvidersSection, SectionData, SectionId,
+  SettingsSection, UiSection, WorkspacesSection,
+} from './types.ts';
+
+/** 全部分区 id（manifest 校验与 adapter registry 共用） */
+export const SECTION_IDS: readonly SectionId[] = [
+  'settings', 'ui', 'providers', 'plugins', 'mcp', 'prompts',
+  'skills', 'agentPresets', 'agentInstructions', 'workspaces', 'pluginFiles',
+  'credentialsStatus', 'secrets', 'sessions', 'self',
+];
+
+/** JSON 分区在 ZIP 内的相对路径；文件类分区（skills 等）走目录前缀，不在此表 */
+export const SECTION_JSON_PATHS: Partial<Record<SectionId, string>> = {
+  settings: 'config/settings.json',
+  ui: 'config/ui.json',
+  providers: 'ai/providers.json',
+  plugins: 'plugins/plugins.json',
+  mcp: 'mcp/servers.json',
+  prompts: 'custom/prompts.json',
+  workspaces: 'workspaces/workspaces.json',
+  credentialsStatus: 'security/credentials.json',
+};
+
+/** 文件类分区在 ZIP 内的目录前缀 */
+export const SECTION_FILE_PREFIXES: Partial<Record<SectionId, string>> = {
+  skills: 'custom/skills/',
+  agentPresets: 'agents/presets/',
+  agentInstructions: 'custom/agent-instructions/',
+  pluginFiles: 'plugin-files/',
+  sessions: 'sessions/',
+  self: 'self/',
+};
+
+/** 该分区是否是「文件类」分区（ZIP 内以真实文件存放而非 JSON） */
+export function isFileSection(sectionId: SectionId): boolean {
+  return sectionId in SECTION_FILE_PREFIXES;
+}
+
+/** 从 ZIP 内 JSON 解析分区数据（深度保护 + 结构校验） */
+export function parseSectionJson<T extends SectionData>(sectionId: SectionId, raw: string): T {
+  const parsed = parseJsonSafe(raw) as T;
+  const issues = validateSectionData(sectionId, parsed);
+  const errors = issues.filter((i) => i.severity === 'error');
+  if (errors.length > 0) {
+    throw new Error(`分区 ${sectionId} 数据无效: ${errors.map((e) => e.message).join('; ')}`);
+  }
+  return parsed;
+}
+
+export interface SectionIssue { path: string; message: string; severity: 'error' | 'warning'; }
+
+/** 分区数据结构基础校验（version 字段 + 顶层形状） */
+export function validateSectionData(sectionId: SectionId, data: unknown): SectionIssue[] {
+  const issues: SectionIssue[] = [];
+  if (data === null || typeof data !== 'object') {
+    return [{ path: '$', message: `分区 ${sectionId} 数据必须是对象`, severity: 'error' }];
+  }
+  const obj = data as Record<string, unknown>;
+  if (obj['version'] !== 1) {
+    issues.push({ path: 'version', message: `分区 ${sectionId} 的 version 必须为 1（收到 ${String(obj['version'])}）`, severity: 'error' });
+    return issues;
+  }
+  switch (sectionId) {
+    case 'settings':
+    case 'ui': {
+      const ns = obj['namespaces'];
+      if (ns === null || typeof ns !== 'object') {
+        issues.push({ path: 'namespaces', message: `分区 ${sectionId} 缺少 namespaces 对象`, severity: 'error' });
+      } else {
+        for (const [name, rec] of Object.entries(ns as Record<string, unknown>)) {
+          if (rec === null || typeof rec !== 'object') {
+            issues.push({ path: `namespaces.${name}`, message: 'namespace 记录必须是对象', severity: 'error' });
+            continue;
+          }
+          const r = rec as Record<string, unknown>;
+          if (typeof r['revision'] !== 'number') issues.push({ path: `namespaces.${name}.revision`, message: 'revision 必须是数字', severity: 'error' });
+          if (!('value' in r)) issues.push({ path: `namespaces.${name}.value`, message: '缺少 value', severity: 'error' });
+          const secrets = r['secrets'];
+          if (secrets !== undefined && !Array.isArray(secrets)) issues.push({ path: `namespaces.${name}.secrets`, message: 'secrets 必须是数组', severity: 'error' });
+        }
+      }
+      break;
+    }
+    case 'providers': {
+      const p = obj['providers'];
+      if (p === null || typeof p !== 'object') issues.push({ path: 'providers', message: '缺少 providers 对象', severity: 'error' });
+      break;
+    }
+    case 'plugins': {
+      if (!Array.isArray(obj['plugins'])) issues.push({ path: 'plugins', message: 'plugins 必须是数组', severity: 'error' });
+      if (obj['patch'] !== undefined && !Array.isArray(obj['patch'])) issues.push({ path: 'patch', message: 'patch 必须是数组', severity: 'error' });
+      // issue #35：patchFiles 会被写到 <home>/profiles/<profile>/<relativePath>，必须逐项校验
+      // （不可信 bundle 的路径穿越向量——与 file 类分区同级的防线）。
+      const patchFiles = obj['patchFiles'];
+      if (patchFiles !== undefined) {
+        if (!Array.isArray(patchFiles)) {
+          issues.push({ path: 'patchFiles', message: 'patchFiles 必须是数组', severity: 'error' });
+        } else {
+          patchFiles.forEach((pf, i) => {
+            const rec = (pf !== null && typeof pf === 'object') ? pf as Record<string, unknown> : null;
+            if (rec === null) {
+              issues.push({ path: `patchFiles[${i}]`, message: 'patch 文件条目必须是对象', severity: 'error' });
+              return;
+            }
+            const rel = rec['relativePath'];
+            if (typeof rel !== 'string' || rel === '' || !isPathSafe(rel)) {
+              issues.push({ path: `patchFiles[${i}].relativePath`, message: 'patch 文件路径必须是安全的相对路径（不得为绝对路径或含 ..）', severity: 'error' });
+            }
+            if (typeof rec['base64'] !== 'string') {
+              issues.push({ path: `patchFiles[${i}].base64`, message: 'patch 文件内容必须是 base64 字符串', severity: 'error' });
+            }
+          });
+        }
+      }
+      break;
+    }
+    case 'mcp': {
+      if (!Array.isArray(obj['servers'])) issues.push({ path: 'servers', message: 'servers 必须是数组', severity: 'error' });
+      break;
+    }
+    case 'prompts': {
+      if (!Array.isArray(obj['prompts'])) issues.push({ path: 'prompts', message: 'prompts 必须是数组', severity: 'error' });
+      break;
+    }
+    case 'workspaces': {
+      if (!Array.isArray(obj['workspaces'])) issues.push({ path: 'workspaces', message: 'workspaces 必须是数组', severity: 'error' });
+      break;
+    }
+    case 'credentialsStatus': {
+      if (!Array.isArray(obj['credentials'])) issues.push({ path: 'credentials', message: 'credentials 必须是数组', severity: 'error' });
+      break;
+    }
+    case 'skills':
+    case 'agentPresets':
+    case 'agentInstructions':
+    case 'pluginFiles':
+    case 'sessions':
+    case 'self': {
+      if (!Array.isArray(obj['files'])) issues.push({ path: 'files', message: 'files 必须是数组', severity: 'error' });
+      break;
+    }
+    default:
+      issues.push({ path: '$', message: `未知分区 ${sectionId}`, severity: 'error' });
+  }
+  return issues;
+}
+
+/** 分区 JSON 载荷的类型收窄（供 adapter / analyzer 使用） */
+export function asSettingsSection(data: unknown): SettingsSection { return data as SettingsSection; }
+export function asUiSection(data: unknown): UiSection { return data as UiSection; }
+export function asProvidersSection(data: unknown): ProvidersSection { return data as ProvidersSection; }
+export function asPluginsSection(data: unknown): PluginsSection { return data as PluginsSection; }
+export function asMcpSection(data: unknown): McpSection { return data as McpSection; }
+export function asPromptsSection(data: unknown): PromptsSection { return data as PromptsSection; }
+export function asWorkspacesSection(data: unknown): WorkspacesSection { return data as WorkspacesSection; }
+export function asCredentialsSection(data: unknown): CredentialsSection { return data as CredentialsSection; }
+export function asFilesSection(data: unknown): FilesSection { return data as FilesSection; }

package/src/schema/index.ts

@@ -0,0 +1,71 @@
+/**
+ * `dsh-config-manager/schema` 的运行时入口（`exports["./schema"]`）。
+ *
+ * 定位：**零 DSH 依赖、零 `node:` 依赖**的 schema 公共面。第三方在不安装
+ * 任何 `@deepseek-ai/*`、React 或 Node 内建模块的前提下，即可：
+ *  - 判定 `manifest.schemaVersion` 的兼容性（`isCurrent` / `isSupported` / `needsMigration` /
+ *    `isTooNew` / `canImport` / `describeVersion` / `UnsupportedSchemaError`）；
+ *  - 取到 `SECTION_IDS` / `SECTION_JSON_PATHS` / `SECTION_FILE_PREFIXES` / `isFileSection`，
+ *    据此实现自己的 importer / exporter（ZIP 内路径与文件类分区前缀的唯一权威）；
+ *  - 引用 Bundle Format v1 的全部载荷类型。
+ *
+ * 为什么需要它：此前的 `exports["./schema"]` 指向 `./lib/schema/types.js`，而 `types.ts`
+ * 是**纯类型文件**——编译产物是一个**空模块**（运行时零导出）。第三方
+ * `import('dsh-config-manager/schema')` 只会拿到 `{}`，`CURRENT_SCHEMA_VERSION` 等
+ * 版本工具**在包外无法导入**（它们定义在 `./versions.ts`，不在任何 exports 映射内）。
+ * 本文件把 `./schema` 变成真实可用的运行时入口。
+ *
+ * 约束（勿破）：本文件只 import 同目录模块（`./config.ts` / `./types.ts` / `./versions.ts`）。
+ * 不 import `../core/*`、不 import `node:*`、不 import 任何 UI / DSH 包——否则会破坏
+ * headless 消费（见 `docs/spec/headless-consumption.md`）与 `tests/architecture-boundaries.test.ts`。
+ */
+
+/* —— 版本判定（唯一出口，业务代码零散落 `if (v === 1)`） —— */
+export {
+  CURRENT_SCHEMA_VERSION,
+  MIN_SUPPORTED_SCHEMA_VERSION,
+  UnsupportedSchemaError,
+  isCurrent,
+  isSupported,
+  needsMigration,
+  isTooNew,
+  canImport,
+  describeVersion,
+} from './versions.ts';
+
+/* —— 分区表（第三方实现 importer/exporter 的路径权威） —— */
+export {
+  SECTION_IDS,
+  SECTION_JSON_PATHS,
+  SECTION_FILE_PREFIXES,
+  isFileSection,
+} from './config.ts';
+
+/* —— 载荷类型（纯类型，运行时零开销） —— */
+export type {
+  Platform,
+  SectionId,
+  EncryptionInfo,
+  Manifest,
+  NamespaceRecord,
+  SettingsSection,
+  UiMigrationNote,
+  UiSection,
+  ProviderEntry,
+  ProvidersSection,
+  PluginEntry,
+  PatchLine,
+  LocalPluginTarball,
+  PluginsSection,
+  McpServerEntry,
+  McpSection,
+  PromptEntry,
+  PromptsSection,
+  WorkspaceRecord,
+  WorkspacesSection,
+  CredentialStatus,
+  CredentialsSection,
+  FileEntry,
+  FilesSection,
+  SectionData,
+} from './types.ts';