dsh-projects-panel 0.1.0

package/lib/index.d.ts

@@ -0,0 +1,464 @@
+import z from "@deepseek-ai/schemastery";
+import { IncomingMessage, ServerResponse } from "node:http";
+import { Context } from "@deepseek-ai/cordis";
+
+//#region src/core/types.d.ts
+
+/**
+ * 领域模型与持久化结构的纯类型定义。
+ *
+ * 本文件只允许类型声明与接口注释，禁止任何运行时代码
+ * （运行时工具函数见 ./workspace.ts）。
+ */
+/** 官方 settingsScope bind 接口最小投影（客户端读写 settings.yaml）。 */
+interface SettingsScopeBind {
+  get(): unknown;
+  update(patch: Record<string, unknown>): void;
+}
+/** 工作区成员关系：记录工作区加入项目的时间。 */
+interface WorkspaceMembership {
+  joinedAt: string;
+}
+/**
+ * 项目树中的一个项目节点。
+ *
+ * 节点既可持有直接子项目（projects），也可持有归属的工作区（workspaces）；
+ * 归档的工作区 id 记录在 archivedProjectIds，但保留在 workspaces 中不再展开。
+ */
+interface ProjectNode {
+  /** 项目名：磁盘目录名，满足 validateProjectName 的约束。 */
+  name: string;
+  /** 可选的宿主工作区绝对路径链接。 */
+  link?: string;
+  description?: string;
+  createdAt: string;
+  updatedAt: string;
+  projectIds: string[];
+  workspaceIds: string[];
+  archivedProjectIds: string[];
+  projects: Record<string, ProjectNode>;
+  workspaces: Record<string, WorkspaceMembership>;
+}
+/** projects.json 的持久化结构：根持有顶层项目与归档项目。 */
+interface ProjectTree {
+  unit: {
+    name: 'project';
+    version: 1;
+  };
+  global: {
+    initialized: boolean;
+  };
+  projectIds: string[];
+  archivedProjectIds: string[];
+  projects: Record<string, ProjectNode>;
+}
+/** 工作区视图：由宿主注入的扁平工作区列表条目。 */
+interface WorkspaceView {
+  /** 官方工作区标识（view id）；跨域稳定键取 workspaceId ?? id。 */
+  id?: string;
+  workspaceId?: string;
+  path: string;
+  name?: string;
+  title?: string;
+  createdAt?: number | string;
+  updatedAt?: number | string;
+  sessionIds?: readonly string[];
+}
+/** 会话级待用户应答交互的类型（官方 ui-approval / ui-user-questions 注册的 kind 收敛）。 */
+type SessionPendingKind = 'approval' | 'plan-review' | 'question';
+/** 会话视图：用于在树中按工作区聚合会话。 */
+interface SessionView {
+  id: string;
+  workspaceId?: string;
+  title?: string;
+  updatedAt?: number;
+  /** 是否正在运行（宿主会话摘要的 running）。 */
+  running?: boolean;
+  /**
+   * 空会话：仅在当前会话为空白时展示（tree.ts 的可见性规则）。
+   * RPC 快照只在面板动作后重拉，故客户端实时列表会把该位只降不升地覆盖
+   * （见 client/session-facts.ts），避免真实会话停留在创建时的 true。
+   */
+  blank?: boolean;
+  /** 子代理会话：不参与树展示。 */
+  subagent?: boolean;
+  archived?: boolean;
+  /**
+   * 客户端实时覆盖（由官方 sessions.list / uiSession 快照合并而来，
+   * 后端 /tree RPC 不产生这些字段）：本次运行结束且未打开的完成提醒。
+   */
+  completed?: boolean;
+  /** 客户端实时覆盖：运行中的子代理后代数量（沿父链累加）。 */
+  runningSubagentCount?: number;
+  /** 客户端实时覆盖：会话级 UI 待用户应答交互。 */
+  pendingInteraction?: SessionPendingKind;
+  /** 客户端实时覆盖：当前列表投影含活动定时任务记录。 */
+  hasActiveSchedule?: boolean;
+}
+/** 插件设置：settings.json 的持久化结构。 */
+interface ProjectsSettings {
+  wordmark?: {
+    markText?: string;
+    name?: string;
+    markImageUrl?: string;
+    brandPrimary?: string;
+  };
+  previewUrl?: string;
+  defaultProject?: string | null;
+  tree?: {
+    expandCurrent?: boolean;
+    filter?: FilterSelection | null;
+  };
+  version: 1;
+}
+/** 树顶层的筛选口径：全部 / 单个项目 / 单个工作区。 */
+type FilterSelection = {
+  kind: 'all';
+} | {
+  kind: 'project';
+  id: string;
+} | {
+  kind: 'workspace';
+  id: string;
+};
+/** 目录浏览的一行（官方 host.listDirectory 投影）：只承载展示字段。 */
+interface DirectoryEntryLike {
+  name: string;
+  path: string;
+  hidden: boolean;
+}
+/** 目录浏览结果（官方 host.listDirectory 响应投影）。 */
+interface DirectoryListingLike {
+  path: string;
+  home: string;
+  crumbs: readonly DirectoryEntryLike[];
+  entries: readonly DirectoryEntryLike[];
+  truncated: boolean;
+}
+/**
+ * 工作区/会话的官方客户端动作集（渲染层注入，纯接口）。
+ *
+ * 方法语义与官方 IWorkspaces/ISessions 一致；实现绑定在插件入口
+ * （client/index.tsx），由宿主注册的官方运行时提供。目录浏览能力
+ * 缺失（browse 能力未启用）时 listDirectory/createDirectory 为
+ * undefined，界面降级为手工输入路径。
+ */
+interface BrowserActions {
+  /** 打开（并选中）会话。 */
+  openSession(sessionId: string): void;
+  /** 在指定工作区（或默认目标）新建/复用空白会话并打开。 */
+  startSession(workspaceId?: string): Promise<void>;
+  /** 幂等创建或解析已存在目录的工作区；返回官方 workspaceId。 */
+  createWorkspace(path: string): Promise<string>;
+  /** 重命名工作区（官方持久化标题）。 */
+  renameWorkspace(workspaceId: string, title: string): Promise<void>;
+  /** 删除工作区注册（目录与会话日志保留）。 */
+  deleteWorkspace(workspaceId: string): Promise<void>;
+  /** 重命名会话（官方持久化标题）。 */
+  renameSession(sessionId: string, title: string): Promise<void>;
+  /** 分叉会话并在完成后打开子会话。 */
+  forkSession(sessionId: string): Promise<void>;
+  /** 归档会话（registry 全局归档集）。 */
+  archiveSession(sessionId: string): Promise<void>;
+  /**
+   * 官方工作区排序（顶层悬浮工作区与按工作区分组模式专用）。
+   *
+   * 语义与官方 insertBefore 一致：省略锚点追加末尾；缺失时界面降级为不可排序。
+   */
+  insertWorkspaceBefore?(workspaceId: string, beforeId?: string): Promise<void>;
+  /**
+   * 官方会话排序（同工作区内专用，不写插件树）。
+   *
+   * 语义与官方 insertSessionBefore 一致；缺失时界面降级为不可排序。
+   */
+  insertSessionBefore?(workspaceId: string, sessionId: string, beforeId?: string): Promise<void>;
+  /** 应用内目录浏览能力（可选）。 */
+  listDirectory?(path?: string, signal?: AbortSignal): Promise<DirectoryListingLike>;
+  /** 应用内新建目录能力（可选）。 */
+  createDirectory?(path: string, name: string): Promise<string>;
+}
+//#endregion
+//#region src/core/workspace.d.ts
+/**
+ * 解析工作区的稳定标识。
+ *
+ * 宿主注入的 WorkspaceView 可能带显式 workspaceId；没有时退化为 view 自身的 id。
+ * 树推导、筛选与展开状态都以该返回值作为统一键。
+ */
+declare function workspaceIdOf(workspace: WorkspaceView): string;
+/**
+ * 把主目录下路径缩写为 `~` 形式（hover 卡展示用，与官方
+ * abbreviateHomePath 语义一致）：home 缺省/空、非 POSIX 路径、
+ * home 为根或不在该 home 下时原样返回。
+ * @param path 绝对路径。
+ * @param home 宿主主目录；缺省或空表示无法缩写。
+ * @returns 缩写后的展示路径。
+ */
+declare function abbreviateHomePath(path: string, home?: string): string;
+//#endregion
+//#region src/host-tree.d.ts
+/** 项目目录集合的磁盘路径：数据根下 projects/ 子目录（不创建）。 */
+declare function projectStoreRoot(root: string): string;
+/** 新建一棵空的项目树：unit 标记沿用 Cordis 数据文件约定。 */
+declare const emptyTree: () => ProjectTree;
+/**
+ * 校验项目名。
+ *
+ * 项目名仅做展示用（目录名 = 项目 ID），因此放宽为：非空、不含路径
+ * 分隔符（/ \）、不含控制字符、长度不超过 255。
+ */
+declare function validateProjectName(name: string): void;
+/**
+ * 校验整棵项目树的根结构：顶层 id 不得重复、必须可解析，
+ * 且活动与归档两个集合不允许出现同一项目。
+ */
+declare function validateProjectTree(tree: unknown): asserts tree is ProjectTree;
+/**
+ * 以「临时文件 + fsync + rename」方式原子写入 JSON。
+ *
+ * rename 在同一文件系统内是原子的，避免读者读到写了一半的文件；
+ * 0o600 保证项目数据目录不被他人在磁盘上读取。
+ */
+declare function atomicWriteJson(file: string, value: unknown): Promise<void>;
+/**
+ * 读取项目树；projects.json 缺失或损坏时以项目目录集合内容重建。
+ *
+ * 缺失（ENOENT）或 JSON 损坏（SyntaxError）都视为首次启动：
+ * 扫描 root/projects 下 UUID 格式的目录，为每个目录建立一个顶层项目
+ * （名称缺省为 id，可由用户后续通过编辑补全）。
+ */
+declare function readProjectTree(root: string): Promise<ProjectTree>;
+/** 校验后原子写入项目树。 */
+declare function writeProjectTree(root: string, tree: ProjectTree): Promise<void>;
+/** 构造一个新项目节点；默认时间戳为当前时间。 */
+declare function newProject(name: string, now?: string, description?: string, link?: string): ProjectNode;
+/** 项目对应的磁盘目录路径：root/projects/<id>（不创建目录）。 */
+declare function projectDirectory(root: string, id: string): string;
+/** link 必须是宿主已有的绝对路径，拒绝相对路径与空值。 */
+declare function isSafeLinkPath(link: string): boolean;
+/** 持有子项目列表的容器：根树或项目节点均含 projectIds/projects。 */
+interface ProjectHolder {
+  projectIds: string[];
+  projects: Record<string, ProjectNode>;
+}
+/**
+ * 断言整树改写未改变任何项目的父归属（换父一律走 moveProject）。
+ *
+ * 比较口径：每个项目 id 的父容器 id（顶层为空串）；新增项目允许
+ * （设置页新建经 project 路由，此处仅防换父脱节），删除项目允许
+ * （归档经 project 路由）。
+ */
+declare function assertNoParentChange(oldTree: ProjectTree, nextTree: ProjectTree): void;
+/**
+ * 断言工作区归属在全树唯一（同一工作区至多出现一次）。
+ *
+ * 仅供整树替换（POST /projects-panel/tree）写边界兜底；日常挂载
+ * 走先摘除再挂载已天然保证唯一，不经此断言。
+ */
+declare function assertWorkspaceUnique(tree: ProjectTree): void;
+/**
+ * 移动项目归属与排序（UUID 身份不变）。
+ *
+ * 项目目录 = projects/<id>/，与名称/归属解耦，因此移动只改树，不碰目录。
+ * 同容器纯排序只改顺序；换父只改父子引用。移动到自身或后代下、
+ * 锚点不存在或锚点已归档时拒绝且不落盘；同容器内锚点指向源自身
+ * 视为无排序变化，同样不落盘。
+ */
+declare function moveProject(root: string, sourceId: string, parentId?: string, beforeId?: string): Promise<void>;
+/**
+ * 在内存树上执行换父（摘除源容器引用并按锚插入目标容器）。
+ *
+ * @param anchor 排序锚（省略=追加目标末尾）。
+ */
+declare function applyProjectMove(tree: ProjectTree, oldHolder: ProjectHolder, targetHolder: ProjectHolder, sourceId: string, node: ProjectNode, anchor: string | undefined): void;
+/**
+ * 挂载工作区到指定项目下（新增成员关系或移动归属）。
+ *
+ * 无论目标如何，都会先把该工作区从原有位置摘除再挂到目标项目，
+ * 保证同一工作区在整棵活动树中至多出现一次；加入时间保留原记录。
+ * parentId 省略时视为「移到顶层」——顶层不记录成员关系，因此等价于
+ * 仅摘除（工作区随后以悬浮节点显示，此时 beforeId 不允许）。
+ * beforeId 省略表示追加到目标末尾，否则插入到锚点之前；锚点等于
+ * 工作区自身或锚点已归属异常时视为无操作或拒绝（锚点须为目标现成员）。
+ */
+declare function attachWorkspace(root: string, workspaceId: string, parentId?: string, beforeId?: string): Promise<void>;
+/** 从活动树摘除某工作区的全部成员关系（官方工作区删除后的清理）。 */
+declare function detachWorkspace(root: string, workspaceId: string): Promise<void>;
+//#endregion
+//#region src/host-project.d.ts
+/** 按 id 深度查找节点，返回节点与其直接父（顶层项目无父）。 */
+declare function findNode(tree: ProjectTree, id: string): {
+  node: ProjectNode;
+  parent?: ProjectNode;
+  path: string[];
+} | undefined;
+/**
+ * 创建项目：建磁盘目录 + 挂入项目树。
+ *
+ * 目录名 = 项目 ID（UUID），与名称解耦。目录创建成功而树写入失败时，
+ * 残留一个孤儿目录，下次启动会通过 readProjectTree 的扫描恢复逻辑被重新挂载。
+ */
+declare function createProject(root: string, input: {
+  name: string;
+  description?: string;
+  link?: string;
+  parentId?: string;
+}): Promise<string>;
+/**
+ * 更新项目：可改名、改描述、改 link。
+ *
+ * 改名只更新 projects.json 的 name 字段，不碰磁盘目录（目录名 = ID，
+ * 与名称解耦）。重名检查在父级（顶层为树根）内进行。
+ */
+declare function updateProject(root: string, id: string, patch: {
+  name?: string;
+  description?: string;
+  link?: string;
+}): Promise<void>;
+/**
+ * 归档项目：移出活动树（加入 archivedProjectIds），不碰磁盘目录。
+ *
+ * 目录名 = ID，与归档状态解耦，恢复零成本，数据零丢失。
+ */
+declare function archiveProject(root: string, id: string): Promise<void>;
+/**
+ * 读取 link 指向目录内的约定文件（如 AGENTS.md 供侧栏摘要展示）。
+ *
+ * @returns 文件不存在时返回 undefined；相对路径、绝对子路径或白名单外的
+ * 文件名一律抛错，防止把任意宿主文件暴露给客户端。
+ */
+declare function readLinkFile(link: string, relative: string): Promise<string | undefined>;
+//#endregion
+//#region src/host-settings.d.ts
+/** settings.json 缺失字段时的默认值（旧路由兼容）。 */
+declare const defaultSettings: ProjectsSettings;
+/**
+ * 读取插件设置（旧路由兼容）：与默认值做浅合并。
+ */
+declare function readSettings(root: string): Promise<ProjectsSettings>;
+/** 写入设置（旧路由兼容）：version 固定为当前结构版本 1。 */
+declare function writeSettings(root: string, settings: ProjectsSettings): Promise<void>;
+/** settings 命名空间名称。 */
+declare const SETTINGS_NAMESPACE = "projects-panel";
+/** projects-panel 命名空间的用户可写结构。 */
+interface ProjectsPanelSettings {
+  /** 工作区（项目分组浏览器）开关。 */
+  workspaces: {
+    enabled: boolean;
+  };
+  /** 系统通知开关。 */
+  notifications: {
+    enabled: boolean;
+  };
+  /** 品牌 mark/name（空 = 不渲染）。 */
+  brand: {
+    mark: string;
+    name: string;
+  };
+  /** 底栏「预演」目标 URL。 */
+  previewUrl: string;
+  /** 新建工作区默认挂入的项目（null = 顶层）。 */
+  defaultProject: string | null;
+  /** 树行为偏好。 */
+  tree: {
+    expandCurrent: boolean;
+  };
+}
+/** projects-panel 命名空间 schema（schemastery）。 */
+declare const PROJECTS_PANEL_SETTINGS_SCHEMA: z<ProjectsPanelSettings>;
+/** base 默认层（schema 校验后与用户层合并）。 */
+declare const PROJECTS_PANEL_SETTINGS_BASE: ProjectsPanelSettings;
+/** 宿主上下文最小投影（包含 settings 服务）。 */
+type HostContextLike = {
+  settings?: {
+    register(namespace: string, schema: unknown, options?: {
+      base?: unknown;
+    }): unknown;
+  };
+};
+/** 注册 projects-panel 设置命名空间到宿主（fail-open：settings 服务缺失时不抛）。 */
+declare function registerSettingsNamespace(ctx: HostContextLike): void;
+//#endregion
+//#region src/index.d.ts
+interface WebServerLike {
+  register(route: {
+    kind: 'exact' | 'prefix';
+    path: string;
+    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+  }): () => void;
+}
+/** 官方 workspace 宿主实体的最小投影（与 @deepseek-ai/dsh-workspace 的 Workspace 同构）。 */
+interface HostWorkspace {
+  id: string;
+  path: string;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+  sessionIds: readonly string[];
+}
+/** 官方 workspace 域服务（ctx.workspaceRegistry）的最小投影。 */
+interface WorkspaceRegistryLike {
+  list(): readonly HostWorkspace[];
+  /** 全局归档会话 id 集合（getter）。 */
+  readonly archivedSessionIds: readonly string[];
+}
+/** 官方 session.list 返回的会话摘要的最小投影（字段对齐 SessionSummary）。 */
+interface HostSessionSummary {
+  sessionId: string;
+  updatedAt: number;
+  running: boolean;
+  blank: boolean;
+  origin?: 'subagent';
+  cwd?: string;
+  projections?: {
+    values: Record<string, unknown>;
+  };
+}
+/** 官方会话控制器服务（ctx.sessionController）的最小投影。 */
+interface SessionControllerLike {
+  /** Remote 信封：list 返回 { items }（与官方 SessionController.list 一致）。 */
+  list(request: Record<string, never>, signal?: AbortSignal): Promise<{
+    items: readonly HostSessionSummary[];
+  }>;
+}
+interface HostContext extends Context {
+  webServer: WebServerLike;
+  workspaceRegistry: WorkspaceRegistryLike;
+  sessionController: SessionControllerLike;
+  /** 官方设置服务（projects-panel 命名空间注册与读取）。 */
+  settings: {
+    register(namespace: string, schema: unknown, options?: {
+      base?: unknown;
+    }): unknown;
+    get(namespace: string): Record<string, unknown>;
+  };
+}
+declare const inject: string[];
+/**
+ * 计算项目数据根目录。
+ *
+ * DSH_PROJECTS_ROOT_DIR 设置时直接采用（支持 "~" 缩写，展开为用户主目录）；
+ * 未设置时回落到 DSH_HOME（缺省 ~/.dsh）下的 dsh-projects-panel 目录。
+ *
+ * @param home 宿主数据根，测试时可注入临时目录
+ */
+declare function projectsRoot(home?: string): string;
+/** 模块解析器：把模块标识符解析为绝对路径。 */
+type ModuleResolver = (id: string) => string;
+/** 清单读取器：从 package.json 绝对路径读出 version 字段。 */
+type ManifestReader = (manifestPath: string) => string | undefined;
+/**
+ * 解析 DSH 官方版本号，与 `dsh --version` 同源：同读 `@deepseek-ai/dsh/package.json`。
+ *
+ * DSH 启动时把安装依赖闭包镜像到 `$DSH_HOME/profiles/node_modules`，插件由自身
+ * 安装位置向上即可解析到该清单，因此结果与 `dsh --version` 恒等；清单不可解析或
+ * 读取失败（非标准安装）时回退插件版本。
+ * @param resolveManifest - 模块解析器，默认取本模块的 createRequire。
+ * @param readManifest - 清单读取器，默认 readPackageVersion。
+ * @returns DSH 版本号；解析失败回退 PLUGIN_VERSION。
+ */
+declare function readDshVersion(resolveManifest?: ModuleResolver, readManifest?: ManifestReader): string;
+/** 插件入口：注册全部 HTTP 路由。数据根目录就绪后注册数据路由，健康检查立即生效。 */
+declare function apply(ctx: HostContext): void;
+//#endregion
+export { BrowserActions, DirectoryEntryLike, DirectoryListingLike, FilterSelection, PROJECTS_PANEL_SETTINGS_BASE, PROJECTS_PANEL_SETTINGS_SCHEMA, ProjectHolder, ProjectNode, ProjectTree, ProjectsPanelSettings, ProjectsSettings, SETTINGS_NAMESPACE, SessionPendingKind, SessionView, SettingsScopeBind, WorkspaceMembership, WorkspaceView, abbreviateHomePath, apply, applyProjectMove, archiveProject, assertNoParentChange, assertWorkspaceUnique, atomicWriteJson, attachWorkspace, createProject, defaultSettings, detachWorkspace, emptyTree, findNode, inject, isSafeLinkPath, moveProject, newProject, projectDirectory, projectStoreRoot, projectsRoot, readDshVersion, readLinkFile, readProjectTree, readSettings, registerSettingsNamespace, updateProject, validateProjectName, validateProjectTree, workspaceIdOf, writeProjectTree, writeSettings };