dsh-manage-session 0.5.1 → 0.5.4

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,33 +1,82 @@
-/**
- * dsh-manage-session 的共享配置面。
- *
- * 与 host 半身（schemastery schema 在 src/index.ts）以及浏览器半身共用同一形状，
- * 使一处 admitted 的值在另一处也 admitted —— 与 dsh-session-search-toggle /
- * dsh-thinking-levels 的 config 面惯例一致。
- */
-
-/** 会话管家运行时配置（设置命名空间 + 组合入口）。 */
-export interface StewardConfig {
-  /** 插件总开关。 */
-  enabled: boolean
-  /** 会话历史文件（归档浏览与清理）。关闭后不注册 history 路由、不渲染「养老院」页签。 */
-  historyFiles?: boolean
-  /** 会话健康检查（体检 → 处方 → 出院）。关闭后不注册 health 路由、不渲染「体检」页签。 */
-  healthCheck?: boolean
-}
-
-/** 缺省值。 */
-export const DEFAULT_CONFIG: Required<StewardConfig> = {
-  enabled: true,
-  historyFiles: true,
-  healthCheck: true,
-}
-
-/** host 半身注册的设置命名空间（与 src/index.ts 保持一致）。 */
-export const STEWARD_SETTINGS_NAMESPACE = 'session-steward'
-
-/** 侧边栏入口 id（客户端注册 id）。 */
-export const STEWARD_ENTRY_ID = 'dsh-manage-session'
-
-/** host 路由前缀（与搜索索引插件的 /switch-search/api 互不干扰）。 */
-export const STEWARD_API_PREFIX = '/session-steward/api'
+/**
+ * dsh-manage-session 的共享配置面（合并包：管家子域 + 搜索索引子域）。
+ *
+ * 与 host 半身（schemastery schema 在 src/index.ts）以及浏览器半身共用同一形状，
+ * 使一处 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
+}
+
+/** 缺省值。 */
+export const DEFAULT_CONFIG: Required<StewardConfig> = {
+  enabled: true,
+  historyFiles: true,
+  healthCheck: true,
+  search: true,
+}
+
+/** host 半身注册的设置命名空间（与 src/index.ts 保持一致）。 */
+export const STEWARD_SETTINGS_NAMESPACE = 'session-steward'
+
+/** 侧边栏入口 id（客户端注册 id）。 */
+export const STEWARD_ENTRY_ID = 'dsh-manage-session'
+
+/** 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/health/attribution.ts

@@ -1,118 +1,118 @@
-/**
- * 归属：把投影 key 指回产出它的插件包。
- *
- * 做法是静态扫描 profile 的 `node_modules`：`<pkg>/lib/index.js` 里
- * `sessionProjections.register({ key: 'xxx' })`（或其定义工厂）会命中
- * `key:\s*['"](\w+)['"]` 正则；据此建立 `投影 key → 包名` 索引。
- * `@deepseek-ai/*` 视为内置（core）；扫不到时如实返回 `unknown`，禁止臆测。
- */
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-import type { GateAttribution } from './gates.ts'
-
-/** 一条归属记录。 */
-export interface ProjectionOwner {
-  key: string
-  /** 包名；内置包以 `@deepseek-ai/` 前缀判定。 */
-  package: string
-  /** 'core' 表示内置包，'plugin' 表示第三方插件。 */
-  kind: 'core' | 'plugin'
-  /** 命中文件（相对 node_modules）。 */
-  entry: string
-}
-
-/** 默认扫描根：profile 的 node_modules。 */
-export function defaultProfileNodeModules(dshHome?: string): string {
-  return join(dshHome ?? join(homedir(), '.dsh'), 'profiles', 'web', 'node_modules')
-}
-
-/** 收集候选包目录（含 @scope/pkg 一层）。 */
-function candidatePackages(root: string): { name: string; dir: string }[] {
-  const out: { name: string; dir: string }[] = []
-  if (!existsSync(root)) return out
-  for (const entry of readdirSync(root, { withFileTypes: true })) {
-    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
-    if (entry.name.startsWith('.')) continue
-    const dir = join(root, entry.name)
-    if (entry.name.startsWith('@')) {
-      let scoped: string[] = []
-      try {
-        scoped = readdirSync(dir)
-      } catch { continue }
-      for (const child of scoped) {
-        out.push({ name: `${entry.name}/${child}`, dir: join(dir, child) })
-      }
-      continue
-    }
-    out.push({ name: entry.name, dir })
-  }
-  return out
-}
-
-/** 单个入口文件的最大扫描字节数（超大 bundle 直接跳过，避免无谓内存与耗时）。 */
-const MAX_SCAN_BYTES = 12 << 20
-
-/** 扫描若干候选入口文件里出现的投影 key。 */
-function keysInFile(file: string): string[] {
-  if (!existsSync(file)) return []
-  let text: string
-  try {
-    if (statSync(file).size > MAX_SCAN_BYTES) return []
-    text = readFileSync(file, 'utf8')
-  } catch {
-    return []
-  }
-  const keys = new Set<string>()
-  const pattern = /key:\s*['"]([A-Za-z_$][\w$]*)['"]/g
-  let match: RegExpExecArray | null
-  while ((match = pattern.exec(text)) !== null) {
-    const key = match[1]
-    if (key !== undefined && key !== '') keys.add(key)
-  }
-  return [...keys]
-}
-
-/**
- * 建立投影 key → 包 的索引。
- * @param nodeModulesRoot - profile 的 node_modules 根。
- * @returns 归属记录（同一 key 多包命中时保留首个并排序稳定）。
- */
-export function buildProjectionOwnerIndex(nodeModulesRoot: string): ProjectionOwner[] {
-  const records: ProjectionOwner[] = []
-  const seen = new Set<string>()
-  for (const pack of candidatePackages(nodeModulesRoot)) {
-    const lib = join(pack.dir, 'lib')
-    let entries: string[] = []
-    try {
-      if (!statSync(lib).isDirectory()) continue
-      entries = readdirSync(lib).filter(name => name.endsWith('.js'))
-    } catch {
-      continue
-    }
-    for (const name of entries) {
-      const file = join(lib, name)
-      for (const key of keysInFile(file)) {
-        if (seen.has(key)) continue
-        seen.add(key)
-        records.push({
-          key,
-          package: pack.name,
-          kind: pack.name.startsWith('@deepseek-ai/') ? 'core' : 'plugin',
-          entry: `${pack.name}/lib/${name}`,
-        })
-      }
-    }
-  }
-  return records.sort((left, right) => left.key.localeCompare(right.key))
-}
-
-/** 索引查询器。 */
-export function createAttributor(index: readonly ProjectionOwner[]): (projection: string) => GateAttribution | undefined {
-  const byKey = new Map(index.map(record => [record.key, record]))
-  return (projection: string) => {
-    const owner = byKey.get(projection)
-    if (owner === undefined) return { projection, package: 'unknown' }
-    return { projection, package: owner.package }
-  }
-}
+/**
+ * 归属：把投影 key 指回产出它的插件包。
+ *
+ * 做法是静态扫描 profile 的 `node_modules`：`<pkg>/lib/index.js` 里
+ * `sessionProjections.register({ key: 'xxx' })`（或其定义工厂）会命中
+ * `key:\s*['"](\w+)['"]` 正则；据此建立 `投影 key → 包名` 索引。
+ * `@deepseek-ai/*` 视为内置（core）；扫不到时如实返回 `unknown`，禁止臆测。
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { GateAttribution } from './gates.ts'
+
+/** 一条归属记录。 */
+export interface ProjectionOwner {
+  key: string
+  /** 包名；内置包以 `@deepseek-ai/` 前缀判定。 */
+  package: string
+  /** 'core' 表示内置包，'plugin' 表示第三方插件。 */
+  kind: 'core' | 'plugin'
+  /** 命中文件（相对 node_modules）。 */
+  entry: string
+}
+
+/** 默认扫描根：profile 的 node_modules。 */
+export function defaultProfileNodeModules(dshHome?: string): string {
+  return join(dshHome ?? join(homedir(), '.dsh'), 'profiles', 'web', 'node_modules')
+}
+
+/** 收集候选包目录（含 @scope/pkg 一层）。 */
+function candidatePackages(root: string): { name: string; dir: string }[] {
+  const out: { name: string; dir: string }[] = []
+  if (!existsSync(root)) return out
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+    if (entry.name.startsWith('.')) continue
+    const dir = join(root, entry.name)
+    if (entry.name.startsWith('@')) {
+      let scoped: string[] = []
+      try {
+        scoped = readdirSync(dir)
+      } catch { continue }
+      for (const child of scoped) {
+        out.push({ name: `${entry.name}/${child}`, dir: join(dir, child) })
+      }
+      continue
+    }
+    out.push({ name: entry.name, dir })
+  }
+  return out
+}
+
+/** 单个入口文件的最大扫描字节数（超大 bundle 直接跳过，避免无谓内存与耗时）。 */
+const MAX_SCAN_BYTES = 12 << 20
+
+/** 扫描若干候选入口文件里出现的投影 key。 */
+function keysInFile(file: string): string[] {
+  if (!existsSync(file)) return []
+  let text: string
+  try {
+    if (statSync(file).size > MAX_SCAN_BYTES) return []
+    text = readFileSync(file, 'utf8')
+  } catch {
+    return []
+  }
+  const keys = new Set<string>()
+  const pattern = /key:\s*['"]([A-Za-z_$][\w$]*)['"]/g
+  let match: RegExpExecArray | null
+  while ((match = pattern.exec(text)) !== null) {
+    const key = match[1]
+    if (key !== undefined && key !== '') keys.add(key)
+  }
+  return [...keys]
+}
+
+/**
+ * 建立投影 key → 包 的索引。
+ * @param nodeModulesRoot - profile 的 node_modules 根。
+ * @returns 归属记录（同一 key 多包命中时保留首个并排序稳定）。
+ */
+export function buildProjectionOwnerIndex(nodeModulesRoot: string): ProjectionOwner[] {
+  const records: ProjectionOwner[] = []
+  const seen = new Set<string>()
+  for (const pack of candidatePackages(nodeModulesRoot)) {
+    const lib = join(pack.dir, 'lib')
+    let entries: string[] = []
+    try {
+      if (!statSync(lib).isDirectory()) continue
+      entries = readdirSync(lib).filter(name => name.endsWith('.js'))
+    } catch {
+      continue
+    }
+    for (const name of entries) {
+      const file = join(lib, name)
+      for (const key of keysInFile(file)) {
+        if (seen.has(key)) continue
+        seen.add(key)
+        records.push({
+          key,
+          package: pack.name,
+          kind: pack.name.startsWith('@deepseek-ai/') ? 'core' : 'plugin',
+          entry: `${pack.name}/lib/${name}`,
+        })
+      }
+    }
+  }
+  return records.sort((left, right) => left.key.localeCompare(right.key))
+}
+
+/** 索引查询器。 */
+export function createAttributor(index: readonly ProjectionOwner[]): (projection: string) => GateAttribution | undefined {
+  const byKey = new Map(index.map(record => [record.key, record]))
+  return (projection: string) => {
+    const owner = byKey.get(projection)
+    if (owner === undefined) return { projection, package: 'unknown' }
+    return { projection, package: owner.package }
+  }
+}