dsh-worktree-groups 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +168 -2
- package/cordis.patch.yml +17 -0
- package/icon.svg +20 -0
- package/lib/activity.d.ts +78 -0
- package/lib/activity.d.ts.map +1 -0
- package/lib/activity.js +241 -0
- package/lib/activity.js.map +1 -0
- package/lib/client.d.ts +78 -0
- package/lib/client.d.ts.map +1 -0
- package/lib/client.js +4280 -0
- package/lib/git.d.ts +109 -0
- package/lib/git.d.ts.map +1 -0
- package/lib/git.js +317 -0
- package/lib/git.js.map +1 -0
- package/lib/icons.d.ts +148 -0
- package/lib/icons.d.ts.map +1 -0
- package/lib/icons.js +144 -0
- package/lib/icons.js.map +1 -0
- package/lib/index.d.ts +32 -0
- package/lib/index.d.ts.map +1 -0
- package/lib/index.js +47 -0
- package/lib/index.js.map +1 -0
- package/lib/ledger.d.ts +97 -0
- package/lib/ledger.d.ts.map +1 -0
- package/lib/ledger.js +276 -0
- package/lib/ledger.js.map +1 -0
- package/lib/live-merge.d.ts +44 -0
- package/lib/live-merge.d.ts.map +1 -0
- package/lib/live-merge.js +227 -0
- package/lib/live-merge.js.map +1 -0
- package/lib/live-state.d.ts +158 -0
- package/lib/live-state.d.ts.map +1 -0
- package/lib/live-state.js +281 -0
- package/lib/live-state.js.map +1 -0
- package/lib/locales.d.ts +71 -0
- package/lib/locales.d.ts.map +1 -0
- package/lib/locales.js +199 -0
- package/lib/locales.js.map +1 -0
- package/lib/projects.d.ts +88 -0
- package/lib/projects.d.ts.map +1 -0
- package/lib/projects.js +418 -0
- package/lib/projects.js.map +1 -0
- package/lib/routes.d.ts +376 -0
- package/lib/routes.d.ts.map +1 -0
- package/lib/routes.js +1875 -0
- package/lib/routes.js.map +1 -0
- package/lib/row-memo.d.ts +34 -0
- package/lib/row-memo.d.ts.map +1 -0
- package/lib/row-memo.js +46 -0
- package/lib/row-memo.js.map +1 -0
- package/lib/sidebar.d.ts +126 -0
- package/lib/sidebar.d.ts.map +1 -0
- package/lib/tree-model.d.ts +1226 -0
- package/lib/tree-model.d.ts.map +1 -0
- package/lib/tree-model.js +2143 -0
- package/lib/tree-model.js.map +1 -0
- package/lib/types.d.ts +98 -0
- package/lib/types.d.ts.map +1 -0
- package/lib/types.js +8 -0
- package/lib/types.js.map +1 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +88 -4
package/lib/routes.d.ts
ADDED
|
@@ -0,0 +1,376 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 宿主 HTTP 路由(契约见 `docs/INTERFACES.md` §1.5)。
|
|
3
|
+
*
|
|
4
|
+
* 五个路由全部挂在 `/dsh-worktree-groups/` 前缀下,用 `ctx.effect` +
|
|
5
|
+
* `ctx.webServer.register({ kind: 'exact', path, handler })` 注册(宿主契约
|
|
6
|
+
* 见 `docs/HOST-CONTRACTS.md` §A3)。全部 handler 都把异常收敛成 JSON,
|
|
7
|
+
* **永不**抛到 HTTP 层(宿主在 handler 抛错时只回 400 空体,客户端拿不到原因)。
|
|
8
|
+
*
|
|
9
|
+
* ## 数据组装(本文件的重头)
|
|
10
|
+
*
|
|
11
|
+
* 侧栏树的数据必须同时覆盖两个事实源,见 `docs/INTERFACES.md` §2.7 裁定 6:
|
|
12
|
+
*
|
|
13
|
+
* | 事实 | 来源 | 为什么不能用另一个 |
|
|
14
|
+
* |---|---|---|
|
|
15
|
+
* | 全量历史会话(含 cwd 已删除的孤儿) | `ctx.sessionPersistence.list()` | `sessions` 只有进程内活着的实例 |
|
|
16
|
+
* | 实时状态(running/blank/updatedAt/title) | `ctx.sessionController.list()` | `sessionPersistence` 只有 `createdAt`、没有 `updatedAt` |
|
|
17
|
+
* | 工作区(id/path/title) | `ctx.workspaceRegistry.list()` | `sessionIds` getter 会实时过滤掉死 cwd 会话(§A4.5) |
|
|
18
|
+
* | worktree 事实 | `scanRepo()`(按 commonDir 去重 + 30s 缓存) | — |
|
|
19
|
+
*
|
|
20
|
+
* 两侧按 `sessionId` **左连接**到全量历史之上:以全量历史为主表,实时状态只补字段。
|
|
21
|
+
* 孤儿会话没有 summary ⇒ `updatedAt` 必须按裁定 7 回退到 `header.createdAt`,
|
|
22
|
+
* 否则会得到 `undefined`(排序 NaN / 排到末尾)。
|
|
23
|
+
*/
|
|
24
|
+
import type { Context } from '@deepseek-ai/cordis';
|
|
25
|
+
import type { ServerResponse } from 'node:http';
|
|
26
|
+
import type { LedgerArchivedProject, LedgerData, LedgerStore } from './ledger.js';
|
|
27
|
+
import type { ArchivedProjectRow, ProjectNode, RepoInfo, SessionRow, WorkspaceRow } from './types.js';
|
|
28
|
+
/** 本插件注册的全部路由路径(导出便于测试与客户端对齐)。 */
|
|
29
|
+
export declare const ROUTE_PATHS: {
|
|
30
|
+
readonly tree: "/dsh-worktree-groups/tree";
|
|
31
|
+
readonly worktreeCreate: "/dsh-worktree-groups/worktree-create";
|
|
32
|
+
readonly worktreeRemove: "/dsh-worktree-groups/worktree-remove";
|
|
33
|
+
readonly reveal: "/dsh-worktree-groups/reveal";
|
|
34
|
+
readonly workspaceOpen: "/dsh-worktree-groups/workspace-open";
|
|
35
|
+
};
|
|
36
|
+
/**
|
|
37
|
+
* git 扫描结果缓存时长(PRD D13:30 秒)。
|
|
38
|
+
*
|
|
39
|
+
* ⚠️ 2026-11-14 PERF3 起,正向缓存改由仓指纹校验 + {@link SCAN_CACHE_MAX_AGE_MS} 兜底,
|
|
40
|
+
* 本常量仅为兼容既有导出保留,不再参与判定。
|
|
41
|
+
*/
|
|
42
|
+
export declare const SCAN_CACHE_TTL_MS = 30000;
|
|
43
|
+
/**
|
|
44
|
+
* `ctx.workspaceRegistry` 的工作区实体(宿主契约 §A4.5 的字段子集)。
|
|
45
|
+
*
|
|
46
|
+
* **刻意不声明 `sessionIds`**:它是会实时过滤的 getter,裁定 6 明文禁止用它做归属
|
|
47
|
+
* 判定(会丢会话)。此前把它投影进 `WorkspaceRow` 纯属冗余,且是给下一个改动者
|
|
48
|
+
* 埋雷 —— 现在从类型层面就取不到它(「靠类型约束」取代「靠注释约束」)。
|
|
49
|
+
*/
|
|
50
|
+
interface HostWorkspaceEntity {
|
|
51
|
+
id?: unknown;
|
|
52
|
+
path?: unknown;
|
|
53
|
+
title?: unknown;
|
|
54
|
+
createdAt?: unknown;
|
|
55
|
+
updatedAt?: unknown;
|
|
56
|
+
}
|
|
57
|
+
/** `ctx.workspaceRegistry`(宿主契约 §A4)。`list()` 是**同步**的。 */
|
|
58
|
+
interface HostWorkspaceRegistry {
|
|
59
|
+
list?: () => HostWorkspaceEntity[];
|
|
60
|
+
create?: (path: string, title?: string) => Promise<HostWorkspaceEntity | undefined>;
|
|
61
|
+
delete?: (id: string) => Promise<boolean>;
|
|
62
|
+
archivedSessionIds?: unknown;
|
|
63
|
+
}
|
|
64
|
+
/** `SessionSummary` 的宽松投影(宿主契约 §A2.2;字段全部按需校验)。 */
|
|
65
|
+
interface SummaryLike {
|
|
66
|
+
sessionId?: unknown;
|
|
67
|
+
id?: unknown;
|
|
68
|
+
updatedAt?: unknown;
|
|
69
|
+
running?: unknown;
|
|
70
|
+
blank?: unknown;
|
|
71
|
+
parentSessionId?: unknown;
|
|
72
|
+
parentSession?: unknown;
|
|
73
|
+
origin?: unknown;
|
|
74
|
+
cwd?: unknown;
|
|
75
|
+
title?: unknown;
|
|
76
|
+
pendingInteraction?: unknown;
|
|
77
|
+
completed?: unknown;
|
|
78
|
+
projections?: {
|
|
79
|
+
values?: {
|
|
80
|
+
title?: unknown;
|
|
81
|
+
};
|
|
82
|
+
};
|
|
83
|
+
}
|
|
84
|
+
/** 指纹一致时缓存的最长复用时间(兜底:指纹覆盖不到的罕见变化,最迟 5 分钟收敛)。 */
|
|
85
|
+
export declare const SCAN_CACHE_MAX_AGE_MS: number;
|
|
86
|
+
/** 清空全部进程内缓存(git 扫描 + 会话列举 + `/tree` 载荷)。测试用;也用于故障后强制重扫。 */
|
|
87
|
+
export declare function clearScanCache(): void;
|
|
88
|
+
/**
|
|
89
|
+
* 收集实时会话摘要,按 `sessionId` 索引。
|
|
90
|
+
*
|
|
91
|
+
* 三级来源,逐级降级(宿主契约 §A2.2 已核实:宿主 `ctx.sessions` 是 SessionStore,
|
|
92
|
+
* 它的 `list()` 返回活着的 `Session` 实例,**不是** `{items, byId}` 快照;
|
|
93
|
+
* 真正的 `SessionSummary` 生产者是 `ctx.sessionController`):
|
|
94
|
+
*
|
|
95
|
+
* 1. `ctx.sessionController.list({})` → `{ items: SessionSummary[] }`(权威、含孤儿)
|
|
96
|
+
* 2. `ctx.sessions.list()`:若元素本身长得像 summary(有 `sessionId` + 数字 `updatedAt`)直接用;
|
|
97
|
+
* 若元素是活的 `Session`(有 `.header`)则从 header 推导最小摘要;
|
|
98
|
+
* 3. `ctx.sessions.list` 若是 observable 快照源(有 `getSnapshot`)则读 `items` / `byId`。
|
|
99
|
+
*
|
|
100
|
+
* 全部缺失时返回空 Map —— 组装侧仍会为每个会话回退到 `header.createdAt`。
|
|
101
|
+
*/
|
|
102
|
+
export declare function loadSessionSummaries(ctx: Context, signal?: AbortSignal): Promise<Map<string, SummaryLike>>;
|
|
103
|
+
/**
|
|
104
|
+
* 读取全量历史会话(**含 cwd 已死**的孤儿),组装成 `SessionRow[]`。
|
|
105
|
+
*
|
|
106
|
+
* 组装规则(`docs/INTERFACES.md` §2.7 裁定 7):
|
|
107
|
+
* `updatedAt = summary.updatedAt ?? header.createdAt ?? 0`,且必须是**有限数字**。
|
|
108
|
+
*
|
|
109
|
+
* 返回 `{ rows, summaries }`:`summaries` 供调用方复用作 summary 存在性判断。
|
|
110
|
+
*/
|
|
111
|
+
export declare function buildSessionRows(ctx: Context, signal?: AbortSignal): Promise<{
|
|
112
|
+
rows: SessionRow[];
|
|
113
|
+
summaries: Map<string, SummaryLike>;
|
|
114
|
+
}>;
|
|
115
|
+
/** 读取工作区注册表(缺失时返回空表 —— 降级不崩)。 */
|
|
116
|
+
export declare function loadWorkspaces(ctx: Context): {
|
|
117
|
+
workspaces: WorkspaceRow[];
|
|
118
|
+
registry: HostWorkspaceRegistry | undefined;
|
|
119
|
+
};
|
|
120
|
+
/** 归档会话集合(用于从全量历史里剔除,客户端再兜一层)。 */
|
|
121
|
+
export declare function loadArchivedSessionIds(registry: HostWorkspaceRegistry | undefined): string[];
|
|
122
|
+
/**
|
|
123
|
+
* **D8**:工作区表的内容签名(用于判断「注册表是否真的变了」)。
|
|
124
|
+
*
|
|
125
|
+
* 为什么不用长度:长度是代理指标。D18 清扫删 1 条 + 宿主同一轮新增 1 条 ⇒ 长度相等,
|
|
126
|
+
* `length !== length` 会误判为「没变」,本轮响应继续用旧表(死工作区行多渲染一轮)。
|
|
127
|
+
*
|
|
128
|
+
* 为什么不用 `updatedAt` 单个字段:宿主对 `title` 重命名与 `delete` 都会动 `updatedAt`,
|
|
129
|
+
* 但**成员增删**必须被检出,所以两者都纳入。签名先按 `workspaceId` 排序,因此与
|
|
130
|
+
* `registry.list()` 的返回顺序无关(顺序变化不应被当成内容变化)。
|
|
131
|
+
*
|
|
132
|
+
* 导出以便单测直接对「同长度不同成员」构造用例断言。
|
|
133
|
+
*/
|
|
134
|
+
export declare function workspaceSignature(workspaces: readonly WorkspaceRow[]): string;
|
|
135
|
+
/** 一次请求要用的全量宿主事实。 */
|
|
136
|
+
export interface TreeSnapshot {
|
|
137
|
+
workspaces: WorkspaceRow[];
|
|
138
|
+
repos: Record<string, RepoInfo>;
|
|
139
|
+
repoByWorkspacePath: Record<string, string>;
|
|
140
|
+
ledger: LedgerData;
|
|
141
|
+
sessions: SessionRow[];
|
|
142
|
+
archivedSessionIds: string[];
|
|
143
|
+
/** 归一化工作区路径 → workspaceId。 */
|
|
144
|
+
workspaceByPath: Record<string, string>;
|
|
145
|
+
/** 白名单:全部已知 worktree 路径(归一化)。 */
|
|
146
|
+
knownWorktreePaths: Set<string>;
|
|
147
|
+
/** 白名单:全部已知 git 仓入口路径(归一化,含 commonDir / mainPath / 全部 worktree)。 */
|
|
148
|
+
knownRepoPaths: Set<string>;
|
|
149
|
+
/**
|
|
150
|
+
* 归一化路径 → 所属仓的 **mainPath**(归一化)。
|
|
151
|
+
*
|
|
152
|
+
* 覆盖 `knownRepoPaths ∪ knownWorktreePaths` 的每一个键。这个表存在的理由是一个
|
|
153
|
+
* 真实的坑:macOS 上 `/var` 是 `/private/var` 的符号链接,`git worktree list`
|
|
154
|
+
* 回的是 realpath 拼法,而 dsh 工作区路径可能是另一种拼法。二者经 `normalizePath`
|
|
155
|
+
* (只做 `resolve`,不做 `realpath`)后仍不相等。因此**白名单命中的拼法**必须与
|
|
156
|
+
* **仓查找用的拼法**来自同一批来源,否则会出现「白名单放行、却找不到仓库」的
|
|
157
|
+
* 自相矛盾状态。本表正是用与白名单完全相同的来源填充的,保证二者一致。
|
|
158
|
+
*/
|
|
159
|
+
mainPathByKnownPath: Map<string, string>;
|
|
160
|
+
/**
|
|
161
|
+
* **已确认磁盘上存在**的工作区路径集合(归一化),喂给 `buildProjects` 的
|
|
162
|
+
* `liveWorkspacePaths`。用于判定「已注册但目录已死」的非 git 工作区。
|
|
163
|
+
*/
|
|
164
|
+
liveWorkspacePaths: Set<string>;
|
|
165
|
+
/**
|
|
166
|
+
* **有正面证据表明是「非主工作树」**的工作区路径集合(归一化)。D18 清扫只允许删这些。
|
|
167
|
+
*
|
|
168
|
+
* 「正面证据」= 该路径出现在 git 扫描的非主 worktree 列表里,或出现在台账
|
|
169
|
+
* `projects[*].worktrees` 里且**不等于该项目记录的 `mainPath`**。
|
|
170
|
+
*
|
|
171
|
+
* 为什么不写成「不是主树就删」:如果一个仓的**整个目录**(含 `.git`)都消失了,
|
|
172
|
+
* git 就扫不出任何 worktree,此时「它是不是主树」**不可判定**。把它当非主树删掉,
|
|
173
|
+
* 会在用户只是临时移走 / 之后重新 clone 时**静默丢掉工作区记录**。
|
|
174
|
+
* D18 的明文禁止项(「主仓自己被删的情况不要自动删记录」)正是这种情形,
|
|
175
|
+
* 因此这里要求**正面证据**,拿不到证据就不动。
|
|
176
|
+
*/
|
|
177
|
+
nonMainWorkspacePaths: Set<string>;
|
|
178
|
+
}
|
|
179
|
+
/** {@link collectSnapshot} 的可注入依赖(测试用;生产走默认实现)。 */
|
|
180
|
+
export interface SnapshotOptions {
|
|
181
|
+
/** 台账存储;缺省时用 `createFileLedger()`(`<DSH home>/worktree-groups.json`)。 */
|
|
182
|
+
ledger?: LedgerStore;
|
|
183
|
+
/** 取消信号。 */
|
|
184
|
+
signal?: AbortSignal;
|
|
185
|
+
/** 「当前时刻」注入点(缓存 TTL 判定 + 台账时间戳),测试可固定。 */
|
|
186
|
+
now?: number;
|
|
187
|
+
/**
|
|
188
|
+
* 复用进程内会话列举缓存(2026-11-14 PERF1,见 {@link cachedSessionRows})。
|
|
189
|
+
* 只有 `/tree` 路由开启;直接调用导出函数时缺省关闭,保持「每次都读宿主」的旧语义。
|
|
190
|
+
*/
|
|
191
|
+
reuseSessions?: boolean;
|
|
192
|
+
}
|
|
193
|
+
/** 会话列举缓存的最长复用时间(兜底:没有任何活动信号时也最迟 30 s 重列一次)。 */
|
|
194
|
+
export declare const SESSION_ROWS_MAX_AGE_MS = 30000;
|
|
195
|
+
/**
|
|
196
|
+
* 收集一次请求需要的全部宿主事实。
|
|
197
|
+
*
|
|
198
|
+
* 全部服务都是**惰性 + 可选**:任何一个缺席都只让对应部分为空,不抛错。
|
|
199
|
+
*/
|
|
200
|
+
export declare function collectSnapshot(ctx: Context, options?: SnapshotOptions): Promise<TreeSnapshot>;
|
|
201
|
+
/**
|
|
202
|
+
* **D18 自动清扫**:注销「目录已死」且「不是其仓主工作树」的 dsh 工作区记录。
|
|
203
|
+
*
|
|
204
|
+
* PRD D18(用户拍板):worktree 被外部 `rm -rf` 后,不应在侧栏留下一行死工作区;
|
|
205
|
+
* 其会话应由 `buildProjects` 的规则 3/4 归入该项目的 history 桶。
|
|
206
|
+
*
|
|
207
|
+
* 安全边界(与 D18 原文一致):
|
|
208
|
+
* - **只碰注册表,不碰磁盘、不碰会话日志**(`registry.delete` 只删一条记录);
|
|
209
|
+
* - **主仓自己的目录被删时不动它** —— 那多半是临时不可达或用户会重建,
|
|
210
|
+
* 自动注销会造成「重启后工作区莫名消失」;
|
|
211
|
+
* - 单个失败不中断整体(收集后返回,由调用方决定是否报告)。
|
|
212
|
+
*
|
|
213
|
+
* 返回**被成功注销**的 workspaceId 列表,便于调用方/测试断言。
|
|
214
|
+
*/
|
|
215
|
+
export declare function sweepDeadWorkspaces(ctx: Context, snapshot: TreeSnapshot): Promise<{
|
|
216
|
+
removed: string[];
|
|
217
|
+
failed: Array<{
|
|
218
|
+
workspaceId: string;
|
|
219
|
+
message: string;
|
|
220
|
+
}>;
|
|
221
|
+
}>;
|
|
222
|
+
/** `POST /dsh-worktree-groups/tree` 的响应体。 */
|
|
223
|
+
export interface TreePayload {
|
|
224
|
+
ok: true;
|
|
225
|
+
projects: ProjectNode[];
|
|
226
|
+
ungrouped: SessionRow[];
|
|
227
|
+
archivedSessionIds: string[];
|
|
228
|
+
workspaceByPath: Record<string, string>;
|
|
229
|
+
archivedProjects: ArchivedProjectRow[];
|
|
230
|
+
}
|
|
231
|
+
/**
|
|
232
|
+
* 组装 `POST /tree` 的完整载荷(导出以便脱离 HTTP 层做端到端验证)。
|
|
233
|
+
*
|
|
234
|
+
* 顺带把本次观察到的事实写回台账(首次/最近见到 worktree、已消失时刻、会话归属)。
|
|
235
|
+
* 台账写失败**不影响**响应(PRD R4:台账只是辅助归属信息)。
|
|
236
|
+
*/
|
|
237
|
+
export declare function buildTreePayload(ctx: Context, options?: SnapshotOptions, precomputed?: TreePayload): Promise<TreePayload>;
|
|
238
|
+
/**
|
|
239
|
+
* 归档一个工作空间(2026-10-21 WSR1/WSR2,AC7)。
|
|
240
|
+
*
|
|
241
|
+
* 将 `projectKey` 记入台账 `archivedProjects`;保留宿主 `workspaceRegistry` 记录不销毁,
|
|
242
|
+
* 使恢复(设置页放出或重新添加同目录)后标题、worktree 与会话原样归位。
|
|
243
|
+
*/
|
|
244
|
+
export declare function archiveWorkspaceProject(ctx: Context, projectKey: string, options?: SnapshotOptions): Promise<{
|
|
245
|
+
ok: boolean;
|
|
246
|
+
archivedProjects: Record<string, LedgerArchivedProject>;
|
|
247
|
+
}>;
|
|
248
|
+
/**
|
|
249
|
+
* 放出(取消归档)工作空间(2026-10-21 WSR2,AC7)。
|
|
250
|
+
*
|
|
251
|
+
* 支持两种匹配方式:
|
|
252
|
+
* 1. `target.projectKey`:设置页点击「放出」时直接按项目键解除归档;
|
|
253
|
+
* 2. `target.path`:用户在首页或侧栏重新添加相同目录(或同 git 仓库下的任意 worktree 目录)
|
|
254
|
+
* 作为工作空间时,自动识别并解除该项目的归档状态。
|
|
255
|
+
*/
|
|
256
|
+
export declare function unarchiveWorkspaceProject(ctx: Context, target: {
|
|
257
|
+
projectKey?: string;
|
|
258
|
+
path?: string;
|
|
259
|
+
}, options?: SnapshotOptions): Promise<{
|
|
260
|
+
ok: boolean;
|
|
261
|
+
unarchivedKeys: string[];
|
|
262
|
+
}>;
|
|
263
|
+
/**
|
|
264
|
+
* 把本次观察写回台账。
|
|
265
|
+
*
|
|
266
|
+
* - `projects[commonDir].worktrees[path]`:首次见到填 `firstSeenAt = lastSeenAt = now`;
|
|
267
|
+
* 再次见到刷新 `lastSeenAt`(并清除 `goneAt` —— 目录又被建回来了);
|
|
268
|
+
* `exists === false` 时首次设置 `goneAt`。
|
|
269
|
+
* - `sessions[sessionId] = { projectKey, worktreePath }`:只记录**本次确实归到某个
|
|
270
|
+
* 活 worktree** 的会话;history 桶里的会话保留台账原值(否则会把历史归属覆盖成空)。
|
|
271
|
+
*/
|
|
272
|
+
/** 台账 `lastSeenAt` 的刷新粒度(2026-11-14 PERF2):同一 worktree 至多每小时写一次。 */
|
|
273
|
+
export declare const LEDGER_LAST_SEEN_REFRESH_MS: number;
|
|
274
|
+
/** 白名单判定的结果:要么给回归一化路径,要么给拒绝原因。 */
|
|
275
|
+
type PathVerdict = {
|
|
276
|
+
ok: true;
|
|
277
|
+
path: string;
|
|
278
|
+
} | {
|
|
279
|
+
ok: false;
|
|
280
|
+
message: string;
|
|
281
|
+
};
|
|
282
|
+
/**
|
|
283
|
+
* **D-N1**:传给 git 的位置参数(分支名 / ref / 路径)的安全校验。
|
|
284
|
+
*
|
|
285
|
+
* 为什么需要它:这些值由调用方指定,并直接拼进 `git worktree add` 的**参数数组**。
|
|
286
|
+
* 数组形式本身挡住了 shell 注入,但**挡不住 git 自己的选项解析** —— 以 `-` 开头的值
|
|
287
|
+
* 会被 git 当成选项执行。实测(git 2.54.0):`baseRef: "--no-checkout"` 会让
|
|
288
|
+
* `git worktree add -b noc <target> --no-checkout` **成功返回**,但 worktree 里只有
|
|
289
|
+
* `.git`、没有任何检出文件,而接口仍返回 `200 {ok:true}` 并自动注册成工作区。
|
|
290
|
+
*
|
|
291
|
+
* 规则刻意宽松:只挡**前导 `-`** 与 NUL / 换行。分支名合法地含有 `/`(`feature/ohos`)
|
|
292
|
+
* 与 `.`(`release/6.1.20`),用「只允许字母数字」之类的白名单会砍掉正常用法。
|
|
293
|
+
*
|
|
294
|
+
* `src/panel-git.ts` 里移植过来的 `isSafeRef` **不在本包内**(已确认:`src/` 下只有
|
|
295
|
+
* `git.ts`,无 `panel-git.ts`),故此处落地一个最小实现。
|
|
296
|
+
*/
|
|
297
|
+
export declare function isSafeGitArg(value: string): boolean;
|
|
298
|
+
/**
|
|
299
|
+
* 把分支名净化为可做目录名的片段(PRD D7:`<主仓名>-<分支名 sanitize>`)。
|
|
300
|
+
*/
|
|
301
|
+
export declare function sanitizeBranchForPath(branch: string): string;
|
|
302
|
+
/** 默认目标路径:`<主仓父目录>/<主仓名>-<分支名 sanitize>`。 */
|
|
303
|
+
export declare function defaultWorktreePath(mainPath: string, branch: string): string;
|
|
304
|
+
/**
|
|
305
|
+
* **D5**:调用方显式传入的 `targetPath` 的安全校验。
|
|
306
|
+
*
|
|
307
|
+
* 为什么需要它:`repoPath` 走严格白名单,而**同样由调用方指定、后果更重**的
|
|
308
|
+
* `targetPath`(git 会在那里铺开整个文件树,且成功后会被 `registry.create()` 自动
|
|
309
|
+
* 注册成 dsh 工作区)此前零校验 —— 一条 POST 就能把 worktree 建到 `/tmp/evil/...`
|
|
310
|
+
* 或仓外任意位置。客户端当前不传该参数(纯 API 面缺口),但后端必须同源收紧。
|
|
311
|
+
*
|
|
312
|
+
* 约束(与 {@link defaultWorktreePath} 的落点算法同构):
|
|
313
|
+
* 1. 必须是**主仓父目录的直接子目录** —— `dirname(targetPath) === dirname(mainPath)`。
|
|
314
|
+
* 这同时挡住 `/tmp/...`、仓内子路径、`..` 越狱(`normalizePath` 已解析过 `..`)。
|
|
315
|
+
* 2. `basename(targetPath)` 必须先以 `basename(mainPath)` 开头(与默认推导的
|
|
316
|
+
* `<主仓名>-<后缀>` 形态一致),避免在用户的项目目录里凭空多出一个无关名字。
|
|
317
|
+
* 3. 不得以 `.` 开头(挡住 `.git`、`.ssh` 之类隐藏目录)。
|
|
318
|
+
*
|
|
319
|
+
* **D-N2**:以上三条都基于 `normalizePath`(`path.resolve`,**只做词法归一、不解析
|
|
320
|
+
* 符号链接**),因此「攻击者先在主仓父目录下建一个指向仓外的符号链接
|
|
321
|
+
* `demo-repo-evil-link -> /仓外目录`」这条路径词法上完全合法 ⇒ 校验通过 ⇒ git 把整个
|
|
322
|
+
* worktree 铺到**链接真身**(仓外),D-5 被绕过。修复方式是让调用方把**已 realpath
|
|
323
|
+
* 解析的主仓父目录**通过 `parentReal` 传进来(见 {@link resolveParentReal}),并以它为准
|
|
324
|
+
* 做第 1 条比较。这样:
|
|
325
|
+
* - 父目录是符号链接 ⇒ 解析后的真实父目录 ≠ 主仓真实父目录 ⇒ 拒绝;
|
|
326
|
+
* - 父目录不存在 / `realpath` 抛错 ⇒ 由调用方拒绝,绝不静默放行。
|
|
327
|
+
*
|
|
328
|
+
* `parentReal` 是**可选第三参**:缺省时退回原词法行为,既有单测的「9 类拒绝 + 放行」
|
|
329
|
+
* 用例无需改签名即可继续通过。
|
|
330
|
+
*
|
|
331
|
+
* 不要求 `targetPath` **等于**默认推导路径:那会砍掉「同名不同后缀」的合法用法,
|
|
332
|
+
* 超出本缺陷的修复范围。
|
|
333
|
+
*
|
|
334
|
+
* @param raw 调用方给的原始 `targetPath`(已由 `bodyString` 取成非空字符串)。
|
|
335
|
+
* @param mainPath 已解析出的主工作树路径。
|
|
336
|
+
* @param parentReal 可选的**已 realpath 解析**的主仓父目录(见 D-N2)。
|
|
337
|
+
* @returns 归一化后的路径,或拒绝原因。
|
|
338
|
+
*/
|
|
339
|
+
export declare function validateTargetPath(raw: string, mainPath: string, parentReal?: string): PathVerdict;
|
|
340
|
+
/**
|
|
341
|
+
* 注册全部 HTTP 路由。前缀统一 `/dsh-worktree-groups/`(契约 §1.5)。
|
|
342
|
+
*
|
|
343
|
+
* 每个路由用独立的 `ctx.effect` 包裹,插件卸载时路由一并撤销(宿主契约硬约束 15)。
|
|
344
|
+
* 每个 handler 内部再包一层 try/catch —— 双保险,保证任何异常都变成 JSON。
|
|
345
|
+
*/
|
|
346
|
+
export declare function registerRoutes(ctx: Context): void;
|
|
347
|
+
/** `POST /worktree-create` 的处理器(导出以便直接单测入参校验)。
|
|
348
|
+
*
|
|
349
|
+
* `options` 用于**测试隔离**:传入 `createFileLedger(tmpdir)` 可确保不会写真实 `~/.dsh`。 */
|
|
350
|
+
export declare function handleWorktreeCreate(ctx: Context, res: ServerResponse, body: Record<string, unknown>, options?: SnapshotOptions): Promise<void>;
|
|
351
|
+
/** `POST /worktree-remove` 的处理器(导出以便直接单测入参校验)。
|
|
352
|
+
*
|
|
353
|
+
* `options` 用于**测试隔离**:传入 `createFileLedger(tmpdir)` 可确保不会写真实 `~/.dsh`。 */
|
|
354
|
+
export declare function handleWorktreeRemove(ctx: Context, res: ServerResponse, body: Record<string, unknown>, options?: SnapshotOptions): Promise<void>;
|
|
355
|
+
/** `POST /reveal` 的处理器(导出以便直接单测入参校验与白名单)。
|
|
356
|
+
*
|
|
357
|
+
* **D11**:`path` 必须命中「已知集合」= `knownWorktreePaths ∪ knownRepoPaths`,
|
|
358
|
+
* 与 `worktree-remove` 同级。该并集已覆盖全部四类已知路径:
|
|
359
|
+
* - 全部 git 扫描出的 worktree(含**未注册**的);
|
|
360
|
+
* - 仓入口 / `mainPath` / `commonDir`;
|
|
361
|
+
* - 台账记过的 worktree 路径;
|
|
362
|
+
* - 全部**已注册 dsh 工作区**路径(`collectSnapshot` 会把它们补进 `knownWorktreePaths`)。
|
|
363
|
+
*
|
|
364
|
+
* 为什么收紧:本端点会执行 `open -R` / `explorer /select,` / `xdg-open`,与
|
|
365
|
+
* `worktree-remove` / `worktree-create` 承担同级的「把本机路径交给外部进程」的风险。
|
|
366
|
+
* 旧实现只校验「路径存在」,等价于一个「任意路径存在性探针 + 文件管理器打开器」,
|
|
367
|
+
* 与另两个端点的安全姿态不一致。
|
|
368
|
+
*
|
|
369
|
+
* 客户端只有一个调用点(`sidebar.tsx` 的 `MENU.reveal`,worktree 行),路径直接来自
|
|
370
|
+
* 同一棵树的节点数据,必定落在白名单内,因此本收紧不破坏正常功能。
|
|
371
|
+
*
|
|
372
|
+
* `options` 用于**测试隔离**:传入 `createFileLedger(tmpdir)` 可确保不会写真实 `~/.dsh`。
|
|
373
|
+
*/
|
|
374
|
+
export declare function handleReveal(ctx: Context, res: ServerResponse, body: Record<string, unknown>, options?: SnapshotOptions): Promise<void>;
|
|
375
|
+
export {};
|
|
376
|
+
//# sourceMappingURL=routes.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAmB,cAAc,EAAE,MAAM,WAAW,CAAA;AAOhE,OAAO,KAAK,EAAE,qBAAqB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAKrG,kCAAkC;AAClC,eAAO,MAAM,WAAW;;;;;;CAMd,CAAA;AAEV;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAAS,CAAA;AAUvC;;;;;;GAMG;AACH,UAAU,mBAAmB;IAC3B,EAAE,CAAC,EAAE,OAAO,CAAA;IACZ,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,2DAA2D;AAC3D,UAAU,qBAAqB;IAC7B,IAAI,CAAC,EAAE,MAAM,mBAAmB,EAAE,CAAA;IAClC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAAA;IACnF,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACzC,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAyBD,mDAAmD;AACnD,UAAU,WAAW;IACnB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,EAAE,CAAC,EAAE,OAAO,CAAA;IACZ,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,WAAW,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE;YAAE,KAAK,CAAC,EAAE,OAAO,CAAA;SAAE,CAAA;KAAE,CAAA;CAC/C;AAqFD,gDAAgD;AAChD,eAAO,MAAM,qBAAqB,QAAa,CAAA;AAK/C,4DAA4D;AAC5D,wBAAgB,cAAc,IAAI,IAAI,CAGrC;AA0KD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,OAAO,EACZ,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAiFnC;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,OAAO,EACZ,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;CAAE,CAAC,CA6CtE;AAuDD,iCAAiC;AACjC,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG;IAC5C,UAAU,EAAE,YAAY,EAAE,CAAA;IAC1B,QAAQ,EAAE,qBAAqB,GAAG,SAAS,CAAA;CAC5C,CAcA;AAED,kCAAkC;AAClC,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,SAAS,GAAG,MAAM,EAAE,CAI5F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAK9E;AAMD,qBAAqB;AACrB,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,YAAY,EAAE,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAC/B,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3C,MAAM,EAAE,UAAU,CAAA;IAClB,QAAQ,EAAE,UAAU,EAAE,CAAA;IACtB,kBAAkB,EAAE,MAAM,EAAE,CAAA;IAC5B,8BAA8B;IAC9B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC,iCAAiC;IACjC,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC/B,oEAAoE;IACpE,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC3B;;;;;;;;;OASG;IACH,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACxC;;;OAGG;IACH,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC/B;;;;;;;;;;;OAWG;IACH,qBAAqB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CACnC;AAED,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,YAAY;IACZ,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAMD,gDAAgD;AAChD,eAAO,MAAM,uBAAuB,QAAS,CAAA;AAoJ7C;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,CA6IxG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAoBzF;AAED,6CAA6C;AAC7C,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,IAAI,CAAA;IACR,QAAQ,EAAE,WAAW,EAAE,CAAA;IACvB,SAAS,EAAE,UAAU,EAAE,CAAA;IACvB,kBAAkB,EAAE,MAAM,EAAE,CAAA;IAC5B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC,gBAAgB,EAAE,kBAAkB,EAAE,CAAA;CACvC;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,eAAoB,EAC7B,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,WAAW,CAAC,CA8GtB;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAA;CAAE,CAAC,CAyCnF;AAED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAC9C,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAyFpD;AAED;;;;;;;;GAQG;AACH,oEAAoE;AACpE,eAAO,MAAM,2BAA2B,QAAc,CAAA;AAqItD,kCAAkC;AAClC,KAAK,WAAW,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAkC9E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED,6CAA6C;AAC7C,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,WAAW,CAqClG;AAiOD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CA4GjD;AAED;;2EAE2E;AAC3E,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CA4Ff;AAED;;2EAE2E;AAC3E,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAoFf;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CA0Bf"}
|