pi-wechat-session-hub 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.
Files changed (51) hide show
  1. package/LICENSE +661 -0
  2. package/README.md +365 -0
  3. package/docs/decisions/0001-ilink-context-token-queue.md +41 -0
  4. package/docs/handoff-next-session.md +134 -0
  5. package/docs/implementation-spec.md +147 -0
  6. package/extensions/wechat-session-hub.ts +589 -0
  7. package/package.json +67 -0
  8. package/scripts/pi-rpc-smoke.mjs +150 -0
  9. package/scripts/probe-wt-capability.mjs +27 -0
  10. package/scripts/start-ui-worker.ps1 +37 -0
  11. package/src/commands/ilink-qr-login-component.ts +148 -0
  12. package/src/commands/project-command-parser.ts +108 -0
  13. package/src/commands/tokenizer.ts +71 -0
  14. package/src/commands/wechat-manager-command-parser.ts +143 -0
  15. package/src/config/defaults.ts +30 -0
  16. package/src/config/paths.ts +56 -0
  17. package/src/config/store.ts +311 -0
  18. package/src/config/types.ts +33 -0
  19. package/src/config/validation.ts +221 -0
  20. package/src/gateway/channel-types.ts +47 -0
  21. package/src/gateway/command-parser.ts +291 -0
  22. package/src/gateway/command-router.ts +1449 -0
  23. package/src/gateway/credential-store.ts +611 -0
  24. package/src/gateway/durable-message-queue.ts +1043 -0
  25. package/src/gateway/gateway-control-ipc.ts +687 -0
  26. package/src/gateway/gateway-runtime.ts +726 -0
  27. package/src/gateway/ui-worker-extension-bridge.ts +1070 -0
  28. package/src/gateway/ui-worker-ipc.ts +1483 -0
  29. package/src/gateway/ui-worker-types.ts +50 -0
  30. package/src/gateway/wechat-ilink/api-client.ts +390 -0
  31. package/src/gateway/wechat-ilink/channel-adapter.ts +320 -0
  32. package/src/gateway/wechat-ilink/cursor-store.ts +134 -0
  33. package/src/gateway/wechat-ilink/qr-login.ts +612 -0
  34. package/src/gateway/wechat-ilink/typing-indicator.ts +133 -0
  35. package/src/gateway/windows-terminal-launcher.ts +247 -0
  36. package/src/projects/project-service.ts +483 -0
  37. package/src/registry/gateway-lease.ts +348 -0
  38. package/src/registry/manager-registry.ts +466 -0
  39. package/src/registry/types.ts +61 -0
  40. package/src/runtime/background-pi-worker.ts +309 -0
  41. package/src/runtime/background-worker-manager.ts +594 -0
  42. package/src/runtime/gateway-daemon.ts +281 -0
  43. package/src/runtime/gateway-lifecycle-operation.ts +308 -0
  44. package/src/runtime/gateway-service-controller.ts +339 -0
  45. package/src/runtime/gateway-worker-manager.ts +181 -0
  46. package/src/runtime/pi-cli.ts +56 -0
  47. package/src/runtime/pi-rpc-client.ts +427 -0
  48. package/src/runtime/ui-worker-manager.ts +1186 -0
  49. package/src/runtime/windows-logon-task-manager.ts +212 -0
  50. package/src/system/process-liveness.ts +88 -0
  51. package/tsconfig.json +19 -0
@@ -0,0 +1,348 @@
1
+ import { execFile } from "node:child_process";
2
+ import { randomUUID } from "node:crypto";
3
+ import { lstat, mkdir, open, readFile, readdir, unlink, utimes } from "node:fs/promises";
4
+ import { join, resolve } from "node:path";
5
+ import { isProcessAlive } from "../system/process-liveness.ts";
6
+ import { promisify } from "node:util";
7
+
8
+ interface GatewayLockMetadata {
9
+ ownerId: string;
10
+ pid: number;
11
+ processBirthId: string;
12
+ token: string;
13
+ acquiredAt: string;
14
+ }
15
+
16
+ const PROCESS_BIRTH_ID_ENV = "PI_WECHAT_MANAGER_PROCESS_BIRTH_ID";
17
+ const PROCESS_BIRTH_ID = currentProcessBirthId();
18
+
19
+ export type GatewayLeaseErrorCode =
20
+ | "gateway_already_running"
21
+ | "gateway_lease_lost"
22
+ | "gateway_acl_setup_failed";
23
+
24
+ /**
25
+ * 表示 Gateway 租约被占用或已丢失。
26
+ */
27
+ export class GatewayLeaseError extends Error {
28
+ /**
29
+ * 创建 Gateway 租约错误。
30
+ *
31
+ * @param code 稳定错误代码。
32
+ * @param message 面向用户的中文错误信息。
33
+ */
34
+ constructor(
35
+ readonly code: GatewayLeaseErrorCode,
36
+ message: string,
37
+ ) {
38
+ super(message);
39
+ this.name = "GatewayLeaseError";
40
+ }
41
+ }
42
+
43
+ /**
44
+ * 通过原子创建 manager.lock 保证一个用户配置目录只有一个 Gateway owner。
45
+ */
46
+ export class GatewayLease {
47
+ readonly directory: string;
48
+ readonly lockPath: string;
49
+ readonly ownerId: string;
50
+ readonly pid: number;
51
+ readonly processBirthId: string;
52
+ private readonly token: string;
53
+ private released = false;
54
+
55
+ /**
56
+ * 创建已取得锁的 Gateway 租约对象。
57
+ *
58
+ * @param directory manager 数据目录。
59
+ * @param lockPath 锁文件路径。
60
+ * @param metadata 锁文件所有者信息。
61
+ */
62
+ private constructor(
63
+ directory: string,
64
+ lockPath: string,
65
+ metadata: GatewayLockMetadata,
66
+ ) {
67
+ this.directory = directory;
68
+ this.lockPath = lockPath;
69
+ this.ownerId = metadata.ownerId;
70
+ this.pid = metadata.pid;
71
+ this.processBirthId = metadata.processBirthId;
72
+ this.token = metadata.token;
73
+ }
74
+
75
+ /**
76
+ * 尝试取得 Gateway owner 租约。
77
+ *
78
+ * @param directory manager 数据目录。
79
+ * @returns 已持有的租约。
80
+ * @throws {GatewayLeaseError} 另一个活跃 owner 持有锁或锁信息不可信时抛出。
81
+ */
82
+ static async acquire(directory: string): Promise<GatewayLease> {
83
+ const canonicalDirectory = resolve(directory);
84
+ try {
85
+ const directoryStat = await lstat(canonicalDirectory);
86
+ if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) {
87
+ throw new GatewayLeaseError(
88
+ "gateway_acl_setup_failed",
89
+ "manager 数据路径不是普通目录; 为避免写入非枢纽位置, Gateway 未启动。",
90
+ );
91
+ }
92
+ } catch (error) {
93
+ if (error instanceof GatewayLeaseError) {
94
+ throw error;
95
+ }
96
+ if (!isNodeError(error) || error.code !== "ENOENT") {
97
+ throw error;
98
+ }
99
+ }
100
+ await mkdir(canonicalDirectory, { recursive: true, mode: 0o700 });
101
+ if (process.platform === "win32" && (await readdir(canonicalDirectory)).length === 0) {
102
+ await secureEmptyWindowsDirectory(canonicalDirectory);
103
+ }
104
+ const lockPath = join(canonicalDirectory, "manager.lock");
105
+ const metadata: GatewayLockMetadata = {
106
+ ownerId: randomUUID(),
107
+ pid: process.pid,
108
+ processBirthId: currentProcessBirthId(),
109
+ token: randomUUID(),
110
+ acquiredAt: new Date().toISOString(),
111
+ };
112
+
113
+ for (let attempt = 0; attempt < 2; attempt += 1) {
114
+ let handle;
115
+ try {
116
+ handle = await open(lockPath, "wx", 0o600);
117
+ } catch (error) {
118
+ if (!isNodeError(error) || error.code !== "EEXIST") {
119
+ throw error;
120
+ }
121
+ const stale = await isStaleLock(lockPath, metadata);
122
+ if (!stale || attempt > 0) {
123
+ throw new GatewayLeaseError(
124
+ "gateway_already_running",
125
+ "Pi 微信会话枢纽 Gateway 已运行, 或 manager.lock 状态不明确; 不会强行启动第二个 poller。",
126
+ );
127
+ }
128
+ try {
129
+ await unlink(lockPath);
130
+ } catch (unlinkError) {
131
+ if (!isNodeError(unlinkError) || unlinkError.code !== "ENOENT") {
132
+ throw new GatewayLeaseError(
133
+ "gateway_already_running",
134
+ "无法安全回收旧 manager.lock, 请确认没有 Gateway 进程后再处理。",
135
+ );
136
+ }
137
+ }
138
+ continue;
139
+ }
140
+
141
+ try {
142
+ await handle.writeFile(`${JSON.stringify(metadata)}\n`, "utf8");
143
+ await handle.sync();
144
+ } catch (error) {
145
+ await handle.close();
146
+ try {
147
+ await unlink(lockPath);
148
+ } catch {
149
+ throw new GatewayLeaseError(
150
+ "gateway_lease_lost",
151
+ "Gateway 锁创建失败且临时锁无法清理。",
152
+ );
153
+ }
154
+ throw error;
155
+ }
156
+ await handle.close();
157
+ return new GatewayLease(canonicalDirectory, lockPath, metadata);
158
+ }
159
+
160
+ throw new GatewayLeaseError(
161
+ "gateway_already_running",
162
+ "无法取得 Gateway owner 租约。",
163
+ );
164
+ }
165
+
166
+ /**
167
+ * 验证当前进程仍持有 manager.lock。
168
+ *
169
+ * @returns 无返回值。
170
+ * @throws {GatewayLeaseError} 锁文件丢失、被替换或租约已释放时抛出。
171
+ */
172
+ async assertOwned(): Promise<void> {
173
+ if (this.released) {
174
+ throw new GatewayLeaseError("gateway_lease_lost", "Gateway owner 租约已释放。");
175
+ }
176
+ try {
177
+ const metadata = JSON.parse(await readFile(this.lockPath, "utf8")) as Partial<GatewayLockMetadata>;
178
+ if (
179
+ metadata.token !== this.token ||
180
+ metadata.ownerId !== this.ownerId ||
181
+ metadata.pid !== this.pid ||
182
+ metadata.processBirthId !== this.processBirthId
183
+ ) {
184
+ throw new GatewayLeaseError(
185
+ "gateway_lease_lost",
186
+ "manager.lock 所有者已改变, 当前进程停止写入 registry。",
187
+ );
188
+ }
189
+ } catch (error) {
190
+ if (error instanceof GatewayLeaseError) {
191
+ throw error;
192
+ }
193
+ throw new GatewayLeaseError(
194
+ "gateway_lease_lost",
195
+ "manager.lock 不可读取, 当前进程停止写入 registry。",
196
+ );
197
+ }
198
+ }
199
+
200
+ /**
201
+ * 更新锁文件 mtime 作为存活心跳, 并先验证 owner token。
202
+ *
203
+ * @returns 心跳时间 ISO 字符串。
204
+ * @throws {GatewayLeaseError} 租约丢失时抛出。
205
+ */
206
+ async heartbeat(): Promise<string> {
207
+ await this.assertOwned();
208
+ const heartbeatAt = new Date();
209
+ try {
210
+ await utimes(this.lockPath, heartbeatAt, heartbeatAt);
211
+ } catch {
212
+ throw new GatewayLeaseError(
213
+ "gateway_lease_lost",
214
+ "manager.lock 心跳写入失败, 当前进程停止写入 registry。",
215
+ );
216
+ }
217
+ return heartbeatAt.toISOString();
218
+ }
219
+
220
+ /**
221
+ * 仅当锁令牌仍匹配时释放 Gateway 租约。
222
+ *
223
+ * @returns 无返回值。
224
+ */
225
+ async release(): Promise<void> {
226
+ if (this.released) {
227
+ return;
228
+ }
229
+ this.released = true;
230
+ try {
231
+ const metadata = JSON.parse(await readFile(this.lockPath, "utf8")) as Partial<GatewayLockMetadata>;
232
+ if (
233
+ metadata.token === this.token &&
234
+ metadata.ownerId === this.ownerId &&
235
+ metadata.pid === this.pid
236
+ ) {
237
+ await unlink(this.lockPath);
238
+ }
239
+ } catch (error) {
240
+ if (!isNodeError(error) || error.code !== "ENOENT") {
241
+ throw error;
242
+ }
243
+ }
244
+ }
245
+ }
246
+
247
+ /**
248
+ * 为新建或空的 manager 目录移除继承 ACL, 仅授予当前用户、SYSTEM 和 Administrators。
249
+ *
250
+ * @param directory 枢纽专属 manager 数据目录。
251
+ * @returns ACL 设置成功时正常结束。
252
+ * @throws {GatewayLeaseError} 无法解析当前 SID 或写入 ACL 时抛出。
253
+ */
254
+ async function secureEmptyWindowsDirectory(directory: string): Promise<void> {
255
+ const execFileAsync = promisify(execFile);
256
+ const systemRoot = process.env.SystemRoot ?? "C:\\Windows";
257
+ const systemDirectory = join(systemRoot, "System32");
258
+ try {
259
+ const identity = await execFileAsync(
260
+ join(systemDirectory, "whoami.exe"),
261
+ ["/user", "/fo", "csv", "/nh"],
262
+ { windowsHide: true, timeout: 5000, maxBuffer: 64 * 1024 },
263
+ );
264
+ const userSid = identity.stdout.match(/S-\d(?:-\d+)+/)?.[0];
265
+ if (!userSid) {
266
+ throw new Error("windows_user_sid_unavailable");
267
+ }
268
+ await execFileAsync(
269
+ join(systemDirectory, "icacls.exe"),
270
+ [
271
+ directory,
272
+ "/inheritance:r",
273
+ "/grant:r",
274
+ `*${userSid}:(OI)(CI)F`,
275
+ "*S-1-5-18:(OI)(CI)F",
276
+ "*S-1-5-32-544:(OI)(CI)F",
277
+ ],
278
+ { windowsHide: true, timeout: 5000, maxBuffer: 64 * 1024 },
279
+ );
280
+ } catch (error) {
281
+ const failureCode = isNodeError(error) ? String(error.code) : error instanceof Error ? error.name : typeof error;
282
+ throw new GatewayLeaseError(
283
+ "gateway_acl_setup_failed",
284
+ `无法为新的 manager 数据目录设置 Windows ACL (${failureCode}); Gateway 未启动, 未创建 manager.lock。`,
285
+ );
286
+ }
287
+ }
288
+
289
+ /**
290
+ * 计算当前 Node 进程的启动标识, 用于识别 PID 被当前进程重用的情况。
291
+ *
292
+ * @returns 包含 PID 和近似启动时间的稳定字符串。
293
+ */
294
+ function currentProcessBirthId(): string {
295
+ const inherited = process.env[PROCESS_BIRTH_ID_ENV];
296
+ if (inherited?.startsWith(`${process.pid}:`)) {
297
+ return inherited;
298
+ }
299
+ const startedAt = Math.floor(Date.now() - process.uptime() * 1000);
300
+ const birthId = `${process.pid}:${startedAt}`;
301
+ process.env[PROCESS_BIRTH_ID_ENV] = birthId;
302
+ return birthId;
303
+ }
304
+
305
+ /**
306
+ * 判断已有锁是否可以安全回收。
307
+ *
308
+ * @param lockPath 锁文件路径。
309
+ * @param current 当前进程的锁信息。
310
+ * @returns 旧 owner 已退出或当前 PID 已被重用时返回 true。
311
+ */
312
+ async function isStaleLock(
313
+ lockPath: string,
314
+ current: GatewayLockMetadata,
315
+ ): Promise<boolean> {
316
+ try {
317
+ const raw = await readFile(lockPath, "utf8");
318
+ const existing = JSON.parse(raw) as Partial<GatewayLockMetadata>;
319
+ if (
320
+ typeof existing.pid !== "number" ||
321
+ !Number.isInteger(existing.pid) ||
322
+ existing.pid <= 0 ||
323
+ typeof existing.processBirthId !== "string" ||
324
+ typeof existing.token !== "string" ||
325
+ typeof existing.ownerId !== "string"
326
+ ) {
327
+ return false;
328
+ }
329
+
330
+ if (existing.pid === current.pid) {
331
+ return existing.processBirthId !== current.processBirthId;
332
+ }
333
+
334
+ return !isProcessAlive(existing.pid);
335
+ } catch {
336
+ return false;
337
+ }
338
+ }
339
+
340
+ /**
341
+ * 判断值是否为 Node.js 文件系统或进程错误。
342
+ *
343
+ * @param error 待检查值。
344
+ * @returns 值带有 Node.js 错误代码时返回 true。
345
+ */
346
+ function isNodeError(error: unknown): error is NodeJS.ErrnoException {
347
+ return error instanceof Error && "code" in error;
348
+ }