dsh-manage-session 0.4.8 → 0.5.3

package/src/client/search/platform.ts

@@ -0,0 +1,136 @@
+/**
+ * Platform detection and the keyboard-label vocabulary, for the client half.
+ *
+ * Why this module exists
+ * ----------------------
+ * A shortcut hint is the one place where a single hard-coded string is wrong
+ * for most users: `⌘K` is meaningless on Windows, `Ctrl K` is wrong on macOS.
+ * The obvious implementation — one `navigator.platform` test — is also the
+ * fragile one: that API is deprecated, and it returns an empty string in some
+ * privacy configurations, which silently degrades every Mac user to the
+ * Windows vocabulary without any error to notice.
+ *
+ * This module is the single owner of both the platform answer and every label
+ * derived from it. The hint rendered in the sidebar, the hint rendered in the
+ * panel footer, and the chord the keydown handler actually matches all read
+ * from here — so a platform fix cannot land in one of them and miss another,
+ * and the advertised key cannot drift away from the bound key.
+ */
+
+/** The navigator fields the detection reads (all optional, all untrusted). */
+export interface NavigatorLike {
+  userAgentData?: { platform?: unknown }
+  platform?: unknown
+  userAgent?: unknown
+}
+
+/**
+ * Resolve the running platform string, three tiers deep.
+ *
+ * 1. UA-CH (`navigator.userAgentData.platform`) — modern and precise.
+ * 2. `navigator.platform` — broadly available, deprecated, and empty in some
+ *    privacy modes.
+ * 3. The UA string — last resort, still non-empty in practice.
+ *
+ * @param nav - the navigator to read; `undefined` is allowed (non-DOM host).
+ * @returns a lower-cased platform string, or `''` when nothing could be read.
+ */
+export function detectPlatform(nav: NavigatorLike | undefined): string {
+  const chPlatform = nav?.userAgentData?.platform
+  if (typeof chPlatform === 'string' && chPlatform !== '') return chPlatform.toLowerCase()
+  const legacy = nav?.platform
+  if (typeof legacy === 'string' && legacy !== '') return legacy.toLowerCase()
+  const agent = nav?.userAgent
+  if (typeof agent === 'string' && agent !== '') return agent.toLowerCase()
+  return ''
+}
+
+/** The keyboard vocabulary for one platform. */
+export interface PlatformLabels {
+  /** The lower-cased platform string these labels were derived from. */
+  platform: string
+  isMac: boolean
+  isWindows: boolean
+  /** Invoke-key modifier: `⌘` on macOS, `Ctrl` elsewhere. */
+  modLabel: string
+  /** Secondary modifier: `⌥` on macOS, `Alt` elsewhere. */
+  altLabel: string
+  /** Shift: `⇧` on macOS, `Shift` elsewhere. */
+  shiftLabel: string
+  /** Confirm: the arrow glyph is legible on every platform. */
+  enterLabel: string
+  /** Escape: `esc` is the macOS spelling, `Esc` the one everywhere else. */
+  escLabel: string
+  /**
+   * The whole invoke chord as one face, ready for a key chip: `⌘K` on macOS,
+   * `Ctrl K` on Windows and Linux. `Ctrl K` keeps the space because `CtrlK`
+   * reads as a word rather than as two keys.
+   */
+  invokeLabel: string
+}
+
+/**
+ * Derive the label vocabulary from a platform string.
+ *
+ * An unrecognised platform — an empty string, or a UA that names neither
+ * system — takes the non-Mac vocabulary on purpose: `Ctrl` is legible to
+ * everyone, while `⌘` is opaque to anyone who has never used a Mac.
+ *
+ * @param platform - the string produced by {@link detectPlatform}.
+ * @returns the label vocabulary for that platform.
+ */
+export function platformLabels(platform: string): PlatformLabels {
+  const isMac = /mac|iphone|ipad|ipod/u.test(platform)
+  const isWindows = /win/u.test(platform)
+  const modLabel = isMac ? '⌘' : 'Ctrl'
+  return {
+    platform,
+    isMac,
+    isWindows,
+    modLabel,
+    altLabel: isMac ? '⌥' : 'Alt',
+    shiftLabel: isMac ? '⇧' : 'Shift',
+    enterLabel: '↵',
+    escLabel: isMac ? 'esc' : 'Esc',
+    invokeLabel: isMac ? `${modLabel}K` : `${modLabel} K`,
+  }
+}
+
+/** Read `globalThis.navigator` without assuming a DOM (or a DOM lib). */
+function currentNavigator(): NavigatorLike | undefined {
+  const candidate = (globalThis as { navigator?: unknown }).navigator
+  if (candidate === null || typeof candidate !== 'object') return undefined
+  return candidate as NavigatorLike
+}
+
+/** The labels for the platform this bundle is running on. */
+export const LABELS: PlatformLabels = platformLabels(detectPlatform(currentNavigator()))
+
+/** The minimal keydown face the chord test reads. */
+export interface KeyChordEvent {
+  key: string
+  ctrlKey: boolean
+  metaKey: boolean
+  altKey: boolean
+  shiftKey: boolean
+}
+
+/**
+ * Whether a keydown event is the invoke chord advertised by
+ * {@link PlatformLabels.invokeLabel}.
+ *
+ * The hint and the binding have to agree: a footer promising `⌘K` while the
+ * handler matches `Ctrl+K` is worse than showing no hint at all. Both sides
+ * call this, so neither can be changed alone. Requiring the other modifier to
+ * be *absent* keeps the two chords distinct instead of letting either one
+ * satisfy both platforms.
+ *
+ * @param event - the keydown payload.
+ * @param isMac - the running platform's macOS-ness, from {@link LABELS}.
+ * @returns `true` when the event is the invoke chord.
+ */
+export function isInvokeChord(event: KeyChordEvent, isMac: boolean): boolean {
+  if (event.key !== 'k' && event.key !== 'K') return false
+  if (event.altKey || event.shiftKey) return false
+  return isMac ? event.metaKey && !event.ctrlKey : event.ctrlKey && !event.metaKey
+}

package/src/config.ts

@@ -1,19 +1,26 @@
 /**
- * dsh-manage-session 的共享配置面。
+ * dsh-manage-session 的共享配置面（合并包：管家子域 + 搜索索引子域）。
  *
  * 与 host 半身（schemastery schema 在 src/index.ts）以及浏览器半身共用同一形状，
- * 使一处 admitted 的值在另一处也 admitted —— 与 dsh-session-search-toggle /
- * dsh-thinking-levels 的 config 面惯例一致。
+ * 使一处 admitted 的值在另一处也 admitted。
+ *
+ * 两个设置命名空间**并存且互不迁移**：
+ * - `session-steward` —— 管家子域（enabled/historyFiles/healthCheck/search 等共享键）；
+ * - `switch-search` —— 搜索子域的历史命名空间，存储键承诺保持稳定（见
+ *   dsh-search-index README「存储键保持稳定，不做迁移」）；0.1.7 起两者实际
+ *   都落在同一 composition entry（configForms），旧宿主才按命名空间分流。
  */
 
 /** 会话管家运行时配置（设置命名空间 + 组合入口）。 */
 export interface StewardConfig {
-  /** 插件总开关。 */
+  /** 插件总开关（合并包唯一 master：关闭后不注册任何子域路由）。 */
   enabled: boolean
   /** 会话历史文件（归档浏览与清理）。关闭后不注册 history 路由、不渲染「养老院」页签。 */
   historyFiles?: boolean
   /** 会话健康检查（体检 → 处方 → 出院）。关闭后不注册 health 路由、不渲染「体检」页签。 */
   healthCheck?: boolean
+  /** 搜索索引子域（`index-*` 路由与侧栏搜索入口）。关闭后索引子域整体停摆。 */
+  search?: boolean
 }
 
 /** 缺省值。 */
@@ -21,6 +28,7 @@ export const DEFAULT_CONFIG: Required<StewardConfig> = {
   enabled: true,
   historyFiles: true,
   healthCheck: true,
+  search: true,
 }
 
 /** host 半身注册的设置命名空间（与 src/index.ts 保持一致）。 */
@@ -29,5 +37,46 @@ export const STEWARD_SETTINGS_NAMESPACE = 'session-steward'
 /** 侧边栏入口 id（客户端注册 id）。 */
 export const STEWARD_ENTRY_ID = 'dsh-manage-session'
 
-/** host 路由前缀（与搜索索引插件的 /switch-search/api 互不干扰）。 */
+/** host 路由前缀（管家子域；与搜索子域的 /switch-search/api 互不干扰）。 */
 export const STEWARD_API_PREFIX = '/session-steward/api'
+
+/** ------------------------------------------------------------------ 搜索子域 */
+
+/** 搜索子域的历史设置命名空间（存储键稳定承诺，永不迁移）。 */
+export const SWITCH_SEARCH_SETTINGS_NAMESPACE = 'switch-search'
+
+/** 搜索子域路由前缀（历史值，浏览器旧 bundle 与快照文件名依赖它，保持不变）。 */
+export const SWITCH_API_PREFIX = '/switch-search/api'
+
+/** 搜索面板打开时的默认模式。 */
+export type SwitchSearchDefaultMode = 'title' | 'content'
+
+/** 搜索子域可调配置（独立于 StewardConfig 的历史形状，字段名保持稳定）。 */
+export interface SwitchSearchConfig {
+  /**
+   * 搜索卡上的「启用」开关。合并包里它与管家 `enabled` 是**同一个**组合入口
+   * 字段（0.1.7 configForms 单 scope）；保留在此处是为了 legacy settingsScope
+   * 回退路径（旧 switch-search 命名空间的存储形状）与设置卡类型不变。
+   */
+  enabled?: boolean
+  /** 面板默认模式。 */
+  defaultMode: SwitchSearchDefaultMode
+  /** 独立索引是否后台自动同步（水位轮询）。 */
+  autoSync?: boolean
+  /** 增量同步间隔（ms）。 */
+  syncIntervalMs?: number
+  /** 整理索引后保留的归档份数。 */
+  archiveKeep?: number
+  /** 独立索引文件的可选绝对目录。 */
+  indexDir?: string
+}
+
+/** 搜索子域缺省值。 */
+export const SWITCH_DEFAULT_CONFIG: Required<SwitchSearchConfig> = {
+  enabled: true,
+  defaultMode: 'title',
+  autoSync: true,
+  syncIntervalMs: 30_000,
+  archiveKeep: 2,
+  indexDir: '',
+}

package/src/host/history/archive-source.ts

@@ -185,6 +185,54 @@ export function pruneArchiveFile(
   throw new Error(lastReason)
 }
 
+/**
+ * 把会话 id 加入存储中枢的 `global.archivedSessionIds`（= 归档,prune 的逆操作）。
+ *
+ * 与 prune 同一写入口与协议（备份 + 临时文件 + 原子改名）；已在集合中的 id
+ * 不重复追加。运行中的宿主把集合留在内存里、只在启动时重载 —— 调用方必须
+ * 提示需要重启 DSH。
+ * @param ids - 要加入归档数组的会话 id。
+ * @param log - 可选日志出口。
+ * @param searchPaths - 可选候选路径覆盖（测试注入用）。
+ * @returns 实际新增数量与操作后的集合总数。
+ */
+export function archiveArchiveFile(
+  ids: readonly string[],
+  log?: (msg: string) => void,
+  searchPaths?: readonly string[],
+): {
+  added: number
+  total: number
+  file?: string
+} {
+  const wanted = new Set(ids)
+  let lastReason = 'workspace storage file not found (searched ~/.dsh/storages/workspace.json)'
+  for (const path of searchPaths ?? storageFileCandidates()) {
+    let added = 0
+    let total = 0
+    const outcome = editWorkspaceDocument(path, (document) => {
+      const global = document.global as { archivedSessionIds?: unknown } | undefined
+      const current = global?.archivedSessionIds
+      if (!Array.isArray(current)) throw new Error(`storage hub "${path}" holds no global.archivedSessionIds array`)
+      const existing = new Set(current.filter((id): id is string => typeof id === 'string'))
+      const fresh = ids.filter((id) => !existing.has(id))
+      if (fresh.length === 0) {
+        added = 0
+        total = existing.size
+        return false
+      }
+      document.global = { ...global, archivedSessionIds: [...current, ...fresh] }
+      added = fresh.length
+      total = existing.size + fresh.length
+      return true
+    }, log)
+    if (!outcome.ok) { lastReason = outcome.reason; continue }
+    if (outcome.changed) log?.(`archive: added ${added} ids; total ${total}`)
+    return { added, total, file: outcome.file }
+  }
+  throw new Error(lastReason)
+}
+
 /** 构造同步器期望的惰性来源面，并记录诊断。 */
 export function createArchiveSource(getRegistry: () => StewardRegistryFace | undefined): {
   read: () => StewardArchiveRead

package/src/host/history/archive.ts

@@ -14,7 +14,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
-import { pruneArchiveFile, readArchiveSet, type StewardRegistryFace } from './archive-source.ts'
+import { archiveArchiveFile, pruneArchiveFile, readArchiveSet, type StewardRegistryFace } from './archive-source.ts'
 import { locateSessionUsage } from './purge.ts'
 
 /** 一行历史文件条目（尽力而为的元数据 + 磁盘占用）。 */
@@ -192,3 +192,58 @@ export function pruneHistory(
   log?.(`archive prune requested ${ids.length}, removed ${result.removed}, remaining ${result.remaining}`)
   return { ok: true, removed: result.removed, remaining: result.remaining, requiresRestart: true }
 }
+
+/** 归档结果。 */
+export interface StewardHistoryArchiveResult {
+  ok: boolean
+  /** 本次新加入归档集合的数量（已在集合中的 id 不重复计）。 */
+  added?: number
+  /** 操作后归档集合总数。 */
+  total?: number
+  requiresRestart?: boolean
+  error?: string
+}
+
+/** 单次归档的最大 id 数（与 prune/purge 一致）。 */
+export const MAX_ARCHIVE_IDS = 5000
+
+/**
+ * `session-history-archive`：把会话批量加入官方归档集合（prune 的逆操作）。
+ * 与 prune 同一条纪律：校验入参 → 备份并原子替换存储文件 → 读回校验 →
+ * 要求重启（宿主内存集合只在启动时重载）。会话文件不动、工作区成员表不动
+ * （归档只改可见性,与宿主 archiveSession 的文件语义一致）。
+ * @param payload - `{ sessionIds: string[] }`。
+ * @param log - 可选日志出口。
+ * @param searchPaths - 可选候选路径覆盖（测试注入用）。
+ */
+export function archiveHistory(
+  payload: unknown,
+  log?: (msg: string) => void,
+  searchPaths?: readonly string[],
+): StewardHistoryArchiveResult {
+  const record = payload as { sessionIds?: unknown } | null
+  if (!Array.isArray(record?.sessionIds) || record.sessionIds.length === 0) {
+    return { ok: false, error: '缺少 sessionIds 数组' }
+  }
+  const ids = [...new Set(record.sessionIds.filter((id): id is string => typeof id === 'string' && id !== ''))]
+  if (ids.length === 0) return { ok: false, error: 'sessionIds 无有效值' }
+  if (ids.length > MAX_ARCHIVE_IDS) return { ok: false, error: `单次最多归档 ${MAX_ARCHIVE_IDS} 个` }
+  let result: { added: number; total: number; file?: string }
+  try {
+    result = archiveArchiveFile(ids, log, searchPaths)
+  } catch (err) {
+    return { ok: false, error: String(err instanceof Error ? err.message : err) }
+  }
+  // 写后校验：读回文件确认目标 id 确实进了归档集合。
+  const after = readArchiveSet(undefined, searchPaths)
+  if (after.source !== 'storage-file') {
+    return { ok: false, error: '写入后无法读回存储文件，无法确认归档结果' }
+  }
+  const now = new Set(after.ids)
+  const missing = ids.filter((id) => !now.has(id))
+  if (missing.length > 0) {
+    return { ok: false, error: `存储文件在写入后仍缺少 ${missing.length} 个目标 id，归档未生效` }
+  }
+  log?.(`archive requested ${ids.length}, added ${result.added}, total ${result.total}`)
+  return { ok: true, added: result.added, total: result.total, requiresRestart: true }
+}

package/src/host/history/favorites.ts

@@ -0,0 +1,71 @@
+/**
+ * 收藏域（R6）—— 插件自有的 JSON 文件，与索引文件/官方存储彻底分离：
+ * 索引会因 schema 重置/影子切换整体更换，收藏不能放里面；官方存储中枢
+ * 只读不写（唯一写方纪律不破）。文件形如
+ * `<dshHome>/storages/session-steward-favorites.json`：
+ * `{ unit: { name, version }, favoriteSessionIds: string[] }`
+ * 原子写（tmp+rename），丢失可重建（收藏只是标记，不是数据）。
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** 收藏文件候选路径（dshHome 注入；测试可覆盖）。 */
+export function favoritesFileCandidates(dshHome: string): string[] {
+  return [join(dshHome, 'storages', 'session-steward-favorites.json')]
+}
+
+/** 读取收藏集合；文件缺失/畸形一律空数组（收藏只是标记，丢失不致命）。 */
+export function listFavorites(searchPaths?: readonly string[]): string[] {
+  for (const path of searchPaths ?? []) {
+    if (!existsSync(path)) continue
+    try {
+      const parsed = JSON.parse(readFileSync(path, 'utf8')) as { favoriteSessionIds?: unknown }
+      if (!Array.isArray(parsed.favoriteSessionIds)) return []
+      return parsed.favoriteSessionIds.filter((id): id is string => typeof id === 'string')
+    } catch {
+      return []
+    }
+  }
+  return []
+}
+
+/** 收藏写入结果。 */
+export interface FavoritesSetResult {
+  ok: boolean
+  /** 操作后收藏总数。 */
+  total?: number
+  error?: string
+}
+
+/** 设置单条收藏状态（原子写）。 */
+export function setFavoriteState(
+  sessionId: string,
+  favorite: boolean,
+  searchPaths?: readonly string[],
+): FavoritesSetResult {
+  const path = searchPaths?.[0]
+  if (path === undefined || path === '') return { ok: false, error: '缺少收藏文件路径' }
+  let ids: string[] = []
+  if (existsSync(path)) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, 'utf8')) as { favoriteSessionIds?: unknown }
+      if (Array.isArray(parsed.favoriteSessionIds)) {
+        ids = parsed.favoriteSessionIds.filter((id): id is string => typeof id === 'string')
+      }
+    } catch { /* 畸形文件按空集合重建 */ }
+  }
+  const without = ids.filter(id => id !== sessionId)
+  const next = favorite ? [...without, sessionId] : without
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    const tmp = `${path}.fav-tmp`
+    writeFileSync(tmp, `${JSON.stringify({
+      unit: { name: 'session-steward-favorites', version: 1 },
+      favoriteSessionIds: next,
+    }, null, 2)}\n`, 'utf8')
+    renameSync(tmp, path)
+    return { ok: true, total: next.length }
+  } catch (err) {
+    return { ok: false, error: String(err instanceof Error ? err.message : err) }
+  }
+}

package/src/host/index/archive-source.ts

@@ -0,0 +1,90 @@
+/**
+ * Official archive-set source resolution.
+ *
+ * Primary: the in-process `workspaceRegistry` service (the same fact the UI
+ * filters by). Fallback: read the canonical storage hub file directly — the
+ * workspace domain persists `archivedSessionIds` under the `global` segment
+ * (storage-json: `~/.dsh/storages/workspace.json`; storage-sqlite variant
+ * exists but the JSON fallback file is what stock web profiles ship).
+ * Resolution order is decided per read; failures degrade to "no archive set"
+ * and are reported through the diagnostics face.
+ *
+ * READ-ONLY by contract. The archive set is WRITTEN by dsh-manage-session
+ * (会话管家 → 病案室); this package only consumes it to keep archived sessions
+ * out of the index. Format contract: `dsh-归档文件格式契约-20260914.md`.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** One resolved archive read: ids plus which source served them. */
+export interface SwitchArchiveRead {
+  ids: readonly string[]
+  source: 'registry' | 'storage-file' | 'none'
+}
+
+/** The workspaceRegistry mirror face (getter only). */
+export interface SwitchRegistryFace {
+  readonly archivedSessionIds: readonly string[]
+}
+
+/** Diagnostics describing how the archive set is being resolved. */
+export interface SwitchArchiveDiagnostics {
+  source: 'registry' | 'storage-file' | 'none'
+  ids: number
+  error?: string
+}
+
+/** DSH storage hub candidates for the workspace domain (json backend). */
+function storageFileCandidates(): string[] {
+  return [
+    join(homedir(), '.dsh', 'storages', 'workspace.json'),
+  ]
+}
+
+/** Parse the storage hub file's global.archivedSessionIds; throw on malformed content. */
+function readStorageFile(path: string): readonly string[] {
+  const parsed = JSON.parse(readFileSync(path, 'utf8')) as {
+    global?: { archivedSessionIds?: unknown }
+  }
+  const ids = parsed.global?.archivedSessionIds
+  if (!Array.isArray(ids)) throw new Error(`storage hub "${path}" holds no global.archivedSessionIds array`)
+  return ids.filter((id): id is string => typeof id === 'string')
+}
+
+/**
+ * Resolve the official archive set once.
+ * @param registry - lazy workspaceRegistry face (may be absent or throw).
+ * @returns the archive ids plus which source served them.
+ */
+export function readArchiveSet(registry?: SwitchRegistryFace): SwitchArchiveRead {
+  if (registry !== undefined) {
+    try {
+      const ids = registry.archivedSessionIds
+      if (Array.isArray(ids)) return { ids, source: 'registry' }
+    } catch { /* registry not started yet — fall through to the file */ }
+  }
+  for (const path of storageFileCandidates()) {
+    if (!existsSync(path)) continue
+    try {
+      return { ids: readStorageFile(path), source: 'storage-file' }
+    } catch { /* malformed file — try the next candidate */ }
+  }
+  return { ids: [], source: 'none' }
+}
+
+/** Build the lazy source face the syncer expects, with diagnostics capture. */
+export function createArchiveSource(getRegistry: () => SwitchRegistryFace | undefined): {
+  read: () => SwitchArchiveRead
+  diagnostics: () => SwitchArchiveDiagnostics
+} {
+  let last: SwitchArchiveDiagnostics = { source: 'none', ids: 0 }
+  return {
+    read: () => {
+      const read = readArchiveSet(getRegistry())
+      last = { source: read.source, ids: read.ids.length }
+      return read
+    },
+    diagnostics: () => ({ ...last }),
+  }
+}