dsh-tiddlywiki 0.27.2 → 0.28.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 (41) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +3 -0
  3. package/cordis.patch.yml +13 -13
  4. package/docs/CHANGELOG.md +2 -1
  5. package/docs/code-review-2026-09-17.md +151 -0
  6. package/docs/features.md +5 -2
  7. package/docs/usage.md +34 -3
  8. package/docs/wiki-split.md +97 -0
  9. package/lib/client.js +54 -27
  10. package/lib/index.js +2803 -517
  11. package/lib/index.js.map +1 -1
  12. package/package.json +5 -4
  13. package/skills/wiki-split/SKILL.md +106 -0
  14. package/src/client/endpoints.ts +37 -0
  15. package/src/client/index.ts +14 -0
  16. package/src/client/knowledge-fab.ts +62 -3
  17. package/src/client/markdown-editor.ts +128 -128
  18. package/src/client/panel.ts +2 -1
  19. package/src/client/settings-page.ts +217 -3
  20. package/src/client/state.ts +39 -39
  21. package/src/client/status-cache.ts +17 -0
  22. package/src/client/styles.ts +27 -0
  23. package/src/client/toast.ts +22 -22
  24. package/src/client/tw-frame.ts +28 -4
  25. package/src/client/wiki-focus.ts +70 -0
  26. package/src/client/wiki-scope-dock.ts +116 -0
  27. package/src/host/admin.ts +175 -35
  28. package/src/host/git.ts +50 -5
  29. package/src/host/path-key.ts +35 -0
  30. package/src/host/prompt.ts +24 -0
  31. package/src/host/repo-committers.ts +149 -0
  32. package/src/host/routes.ts +254 -81
  33. package/src/host/seeds.ts +51 -10
  34. package/src/host/session-scope.ts +154 -0
  35. package/src/host/skill-install.ts +121 -0
  36. package/src/host/tools.ts +141 -49
  37. package/src/host/wiki-farm.ts +417 -0
  38. package/src/host/wiki-instance.ts +596 -0
  39. package/src/host/wiki-registry.ts +601 -0
  40. package/src/host/wiki.ts +19 -0
  41. package/src/index.ts +686 -459
@@ -0,0 +1,417 @@
1
+ /**
2
+ * The multi-wiki farm (v0.28.0) — owns "which knowledge bases should be
3
+ * RUNNING", and reconciles the running set against the registry.
4
+ *
5
+ * WHY THIS IS A SEPARATE, PURE-ORCHESTRATION CLASS
6
+ * ------------------------------------------------
7
+ * The dangerous part of multi-wiki is not spawning a process; it is the
8
+ * DIFF — what to start, what to stop, what to leave alone, and what must be
9
+ * recycled because its folder changed. Getting that wrong either leaks TW
10
+ * children (orphan processes holding ports) or silently drops a wiki the user
11
+ * still has open.
12
+ *
13
+ * So the farm knows nothing about TiddlyWiki: `createRuntime` is injected, and
14
+ * `scripts/verify-wiki-farm.mjs` drives the whole reconciliation with fakes that
15
+ * only record the calls they received. The rules can then be asserted in
16
+ * milliseconds instead of minutes.
17
+ *
18
+ * THE RUNNING-SET RULES
19
+ * ---------------------
20
+ * single mode → ONLY the default entry runs (the registry in single mode is
21
+ * normally a one-entry registry synthesized from the legacy
22
+ * pointer file, so this is defensive as well as correct).
23
+ * multi mode → every entry with `autostart: true` runs at boot; anything
24
+ * else starts on demand (`startEntry`) — e.g. when a human
25
+ * opens that wiki's panel or a session is scoped to it.
26
+ *
27
+ * A FOLDER CHANGE RECYCLES THE RUNTIME. `WikiServer.setLocation()` refuses to
28
+ * repoint while a child is running, and a running instance holds an fs watcher
29
+ * + auto-committer on the OLD folder. Stopping and creating a fresh runtime is
30
+ * the only sequence that cannot leave half the object describing wiki A while
31
+ * the other half serves wiki B.
32
+ *
33
+ * ONE FAILURE MUST NOT TAKE THE FARM DOWN. A wiki that fails to start is KEPT
34
+ * in the running map (its child may still be coming up — WikiServer arms a
35
+ * late-ready watch) and the failure is reported in `FarmChange.errors`, so one
36
+ * broken folder cannot stop the other knowledge bases from serving.
37
+ *
38
+ * @module dsh-tiddlywiki/host/wiki-farm
39
+ */
40
+ import { join } from 'node:path'
41
+ import { isInsidePath } from './path-key.ts'
42
+ import { defaultEntry, entryPath, type WikiEntry, type WikiRegistry } from './wiki-registry.ts'
43
+
44
+ /**
45
+ * What the farm needs from one knowledge base's runtime.
46
+ * `WikiInstance` (host/wiki-instance.ts) satisfies this structurally.
47
+ */
48
+ export interface WikiRuntime {
49
+ /** Registry entry currently served (id/label/flags/path live here). */
50
+ readonly entry: WikiEntry
51
+ /** Absolute folder currently served. */
52
+ readonly path: string
53
+ /** True once `dispose()` ran: such a runtime must never be started again. */
54
+ readonly isDisposed: boolean
55
+ start(): Promise<void>
56
+ stop(): Promise<void>
57
+ dispose(): Promise<void>
58
+ updateEntry(entry: WikiEntry): void
59
+ }
60
+
61
+ export interface WikiFarmOptions<T extends WikiRuntime = WikiRuntime> {
62
+ /** Build a runtime for one entry (injected so tests can use fakes). */
63
+ createRuntime: (entry: WikiEntry) => T
64
+ log?: (message: string) => void
65
+ }
66
+
67
+ /** What one `apply()`/`startAll()` actually did (logging + settings-page回执). */
68
+ export interface FarmChange {
69
+ /** Ids whose child was spawned by this call. */
70
+ started: string[]
71
+ /** Ids whose child was stopped AND released by this call. */
72
+ stopped: string[]
73
+ /** Ids whose entry was refreshed in place (flags/label — no restart). */
74
+ updated: string[]
75
+ /** Ids running once the call settled. */
76
+ running: string[]
77
+ /** Start/stop failures; a failing wiki never blocks the others. */
78
+ errors: Array<{ id: string; message: string }>
79
+ }
80
+
81
+ /**
82
+ * `T` is the concrete runtime type: the host instantiates
83
+ * `WikiFarm<WikiInstance>` so it can reach instance-only members (config store,
84
+ * bootstrap, committer) without a cast; tests instantiate the default with fakes.
85
+ */
86
+ /**
87
+ * The wiki id a request asks for (`?wiki=<id>`), or undefined when it asks for
88
+ * none. Extracted so the host wiring and the verification harness read the
89
+ * selector the SAME way — a second copy of "how do I parse ?wiki=" is exactly
90
+ * the drift this repo keeps paying for.
91
+ */
92
+ export function wikiIdFromRequest(req: { url?: string | undefined }): string | undefined {
93
+ try {
94
+ const id = new URL(req.url ?? '/', 'http://127.0.0.1').searchParams.get('wiki')
95
+ return id !== null && id.length > 0 ? id : undefined
96
+ } catch {
97
+ return undefined
98
+ }
99
+ }
100
+
101
+ /**
102
+ * Which runtime does this request target?
103
+ *
104
+ * `?wiki=<id>` naming a RUNNING wiki → that one
105
+ * anything else (no selector, unknown id, wiki not running)
106
+ * → the farm's default runtime
107
+ *
108
+ * An unknown id falls back instead of 404ing on purpose: the selector comes
109
+ * from links the user may have bookmarked, and a stale one must not strand them
110
+ * on a broken editor. It also means `?wiki=` can never be used to reach a wiki
111
+ * that is not running — starting one is an explicit action, not a side effect
112
+ * of a GET.
113
+ */
114
+ export function targetRuntimeFor<T extends WikiRuntime>(farm: WikiFarm<T> | undefined, req: { url?: string | undefined }): T | undefined {
115
+ const id = wikiIdFromRequest(req)
116
+ if (id === undefined) return farm?.defaultRuntime()
117
+ return farm?.runtime(id) ?? farm?.defaultRuntime()
118
+ }
119
+
120
+ /**
121
+ * The knowledge base the AGENT works on for one session, plus why it might be
122
+ * none (v0.28.0).
123
+ *
124
+ * The rules, in order:
125
+ * 1. the session's EXPLICIT scope, when it names a wiki that exists — and is
126
+ * `agentVisible`: a hidden wiki must stay unreachable even if a stale
127
+ * selection points at it;
128
+ * 2. the registry's DEFAULT, when it is visible;
129
+ * 3. the first visible entry.
130
+ *
131
+ * Two deliberate refusals:
132
+ *
133
+ * - an explicit scope that is visible but NOT RUNNING yields an ERROR, never a
134
+ * silent fallback to another wiki. Quietly writing the user's note into a
135
+ * different knowledge base is the single worst failure this feature can
136
+ * have, and "the selector said X" must win over convenience.
137
+ * - nothing visible → no runtime and a reason the tool can say out loud,
138
+ * instead of guessing a wiki the user asked to hide.
139
+ */
140
+ export interface AgentScope<T extends WikiRuntime> {
141
+ /** The live runtime to act on (undefined = act on nothing). */
142
+ runtime?: T
143
+ /** The entry the scope resolved to (for labels, even when it cannot serve). */
144
+ entry?: WikiEntry
145
+ /** Why there is no runtime — an actionable sentence for the tool error. */
146
+ reason?: string
147
+ }
148
+
149
+ export function resolveAgentScope<T extends WikiRuntime>(
150
+ farm: WikiFarm<T> | undefined,
151
+ scopes: Record<string, string>,
152
+ sessionId: string | undefined,
153
+ ): AgentScope<T> {
154
+ if (farm === undefined) return { reason: '知识库插件尚未就绪(还没读完清单)' }
155
+ const registry = farm.registry
156
+ const byId = new Map(registry.wikis.map((entry) => [entry.id, entry]))
157
+
158
+ if (sessionId !== undefined) {
159
+ const wantedId = scopes[sessionId]
160
+ const explicit = wantedId === undefined ? undefined : byId.get(wantedId)
161
+ if (explicit !== undefined && explicit.agentVisible) {
162
+ const runtime = farm.runtime(explicit.id)
163
+ if (runtime !== undefined) return { runtime, entry: explicit }
164
+ return { entry: explicit, reason: `本会话作用域指定的知识库「${explicit.label}」当前没有运行,请先在界面上启动它再试` }
165
+ }
166
+ }
167
+
168
+ const visible = registry.wikis.filter((entry) => entry.agentVisible)
169
+ if (visible.length === 0) return { reason: '当前没有对 Agent 可见的知识库(可在设置里把某个库设为对 Agent 可见)' }
170
+ const preferred = defaultEntry({ ...registry, wikis: visible })
171
+ const order = preferred === undefined ? visible : [preferred, ...visible.filter((entry) => entry.id !== preferred.id)]
172
+ for (const entry of order) {
173
+ const runtime = farm.runtime(entry.id)
174
+ if (runtime !== undefined) return { runtime, entry }
175
+ }
176
+ // Nothing visible is running: name the one we WOULD use so the sentence is
177
+ // actionable ("start X"), rather than a vague "no wiki".
178
+ return { entry: order[0], reason: `知识库「${order[0]?.label ?? ''}」当前没有运行,请先在界面上启动它再试` }
179
+ }
180
+
181
+ export class WikiFarm<T extends WikiRuntime = WikiRuntime> {
182
+ private registryValue: WikiRegistry
183
+ private readonly runtimes = new Map<string, T>()
184
+ private errors: Array<{ id: string; message: string }> = []
185
+ private readonly log: (message: string) => void
186
+
187
+ constructor(registry: WikiRegistry, private readonly options: WikiFarmOptions<T>) {
188
+ this.registryValue = registry
189
+ this.log = options.log ?? ((message) => { console.warn('[dsh-tiddlywiki]', message) })
190
+ }
191
+
192
+ /** The registry the farm is currently reconciling against. */
193
+ get registry(): WikiRegistry {
194
+ return this.registryValue
195
+ }
196
+
197
+ /** Ids with a live runtime (order = start order). */
198
+ runningIds(): string[] {
199
+ return [...this.runtimes.keys()]
200
+ }
201
+
202
+ /** The runtime for `id`, or undefined when it is not running. */
203
+ runtime(id: string): T | undefined {
204
+ return this.runtimes.get(id)
205
+ }
206
+
207
+ /** Every running runtime, in start order (plugin-wide tuning walks this). */
208
+ allRuntimes(): T[] {
209
+ return [...this.runtimes.values()]
210
+ }
211
+
212
+ /**
213
+ * The running wikis whose CONTENT a pull just touched (v0.28.0).
214
+ *
215
+ * `changedFiles` are REPOSITORY-relative (what `git diff --name-only` prints),
216
+ * and a wiki is affected when the absolute form of one of them lands inside
217
+ * its folder. With several wikis sharing one repository this is what keeps a
218
+ * pull from restarting — and interrupting whoever is editing — a wiki nothing
219
+ * happened to.
220
+ */
221
+ affectedBy(repoRoot: string, changedFiles: readonly string[]): T[] {
222
+ if (changedFiles.length === 0) return []
223
+ const affected: T[] = []
224
+ for (const runtime of this.runtimes.values()) {
225
+ if (changedFiles.some((file) => isInsidePath(runtime.path, join(repoRoot, file)))) affected.push(runtime)
226
+ }
227
+ return affected
228
+ }
229
+
230
+ /**
231
+ * The runtime legacy/agent traffic falls back to: the registry default when
232
+ * it is running, else the first running one. Undefined = nothing is up.
233
+ */
234
+ defaultRuntime(): T | undefined {
235
+ const preferred = defaultEntry(this.registryValue)
236
+ if (preferred !== undefined) {
237
+ const match = this.runtimes.get(preferred.id)
238
+ if (match !== undefined) return match
239
+ }
240
+ return this.runtimes.values().next().value
241
+ }
242
+
243
+ /**
244
+ * Adopt a registry WITHOUT reconciling the running set.
245
+ *
246
+ * The single-mode folder switch MUST keep `switchWiki()`'s rollback semantics
247
+ * (stop → repoint → start → bootstrap, and on failure put the old wiki back),
248
+ * so it performs the move itself and only needs the farm to agree afterwards.
249
+ * Going through `apply()` there would reconcile a runtime the caller just
250
+ * repointed — stopping and rebuilding the very wiki it had just started.
251
+ */
252
+ syncRegistry(next: WikiRegistry): void {
253
+ this.registryValue = next
254
+ }
255
+
256
+ /** May this entry run AT ALL under the current mode? (removed / mode flip) */
257
+ private visible(entry: WikiEntry): boolean {
258
+ if (this.registryValue.mode === 'multi') return true
259
+ return entry.id === this.registryValue.defaultId
260
+ }
261
+
262
+ /** Should this entry ATOMICALLY come up at boot (mode + autostart)? */
263
+ shouldRun(entry: WikiEntry): boolean {
264
+ if (!this.visible(entry)) return false
265
+ if (this.registryValue.mode === 'single') return true
266
+ return entry.autostart === true
267
+ }
268
+
269
+ /** Ids that boot with the plugin (settings page shows this as 「开局自启」). */
270
+ autoStartIds(): string[] {
271
+ return this.registryValue.wikis.filter((entry) => this.shouldRun(entry)).map((entry) => entry.id)
272
+ }
273
+
274
+ /**
275
+ * BOOT: start every entry the mode/autostart asks for.
276
+ *
277
+ * Nothing is running yet, so there is nothing to reconcile — this IS the
278
+ * "开局全起" rule, literally. `apply()` below is the config-CHANGE path and
279
+ * deliberately does less.
280
+ */
281
+ async startAll(): Promise<FarmChange> {
282
+ const change: FarmChange = { started: [], stopped: [], updated: [], running: [], errors: [] }
283
+ this.errors = []
284
+ for (const entry of this.registryValue.wikis) {
285
+ if (!this.shouldRun(entry)) continue
286
+ await this.startEntry(entry)
287
+ change.started.push(entry.id)
288
+ }
289
+ change.running = this.runningIds()
290
+ change.errors = [...this.errors]
291
+ return change
292
+ }
293
+
294
+ /**
295
+ * Reconcile the running set against `next` — a CONFIG CHANGE (add / edit /
296
+ * remove an entry, or flip the mode).
297
+ *
298
+ * The rules are deliberately the CONSERVATIVE ones, because a config edit is
299
+ * not a boot:
300
+ *
301
+ * · an entry that is GONE, or hidden by a mode flip, must stop;
302
+ * · an entry that is NEWLY ADDED and should auto-start does start;
303
+ * · everything else keeps whatever running state it has —
304
+ * turning `autostart` OFF does not kill a wiki the user has open
305
+ * (`autostart` means "come up at boot"; the next boot honours the new
306
+ * value), and re-saving an unrelated field never resurrects a wiki the
307
+ * user stopped by hand;
308
+ * · a folder change recycles the runtime (setLocation refuses while running).
309
+ *
310
+ * This was found by `scripts/verify-wiki-farm-boot.mjs`: re-asserting the boot
311
+ * rule on every save meant "I started C by hand, then added a wiki" silently
312
+ * stopped C. Explicit start/stop stay explicit (`startEntry`/`stopEntry`).
313
+ */
314
+ async apply(next: WikiRegistry): Promise<FarmChange> {
315
+ const change: FarmChange = { started: [], stopped: [], updated: [], running: [], errors: [] }
316
+ this.errors = []
317
+ const previousIds = new Set(this.registryValue.wikis.map((entry) => entry.id))
318
+ this.registryValue = next
319
+ const byId = new Map(next.wikis.map((entry) => [entry.id, entry]))
320
+
321
+ // 1. Release what is gone or hidden by the mode.
322
+ for (const id of [...this.runtimes.keys()]) {
323
+ const entry = byId.get(id)
324
+ if (entry === undefined || !this.visible(entry)) {
325
+ await this.stopEntry(id)
326
+ change.stopped.push(id)
327
+ }
328
+ }
329
+
330
+ // 2. Adopt.
331
+ for (const entry of next.wikis) {
332
+ const runtime = this.runtimes.get(entry.id)
333
+ if (runtime === undefined) {
334
+ if (!previousIds.has(entry.id) && this.shouldRun(entry)) {
335
+ await this.startEntry(entry)
336
+ change.started.push(entry.id)
337
+ }
338
+ continue
339
+ }
340
+ if (runtime.path !== entryPath(entry)) {
341
+ // Folder change: recycle (see the module header).
342
+ await this.stopEntry(entry.id)
343
+ change.stopped.push(entry.id)
344
+ if (this.shouldRun(entry)) {
345
+ await this.startEntry(entry)
346
+ change.started.push(entry.id)
347
+ }
348
+ continue
349
+ }
350
+ runtime.updateEntry(entry)
351
+ change.updated.push(entry.id)
352
+ }
353
+
354
+ change.running = this.runningIds()
355
+ change.errors = [...this.errors]
356
+ return change
357
+ }
358
+
359
+ /**
360
+ * Start ONE wiki on demand (a panel was opened, a session was scoped to it, a
361
+ * route named it). No-op when it is already running.
362
+ */
363
+ async startEntry(entry: WikiEntry): Promise<void> {
364
+ if (this.runtimes.has(entry.id)) return
365
+ let runtime: T
366
+ try {
367
+ runtime = this.options.createRuntime(entry)
368
+ } catch (err) {
369
+ this.record(entry.id, err)
370
+ return
371
+ }
372
+ this.runtimes.set(entry.id, runtime)
373
+ try {
374
+ await runtime.start()
375
+ } catch (err) {
376
+ // KEEP the runtime: the child may still be coming up (WikiServer arms a
377
+ // late-ready watch), and callers must be able to stop it. Reporting the
378
+ // failure is what makes it observable.
379
+ this.record(entry.id, err)
380
+ }
381
+ }
382
+
383
+ /** Stop one wiki (drain + stop) and release its runtime. No-op when absent. */
384
+ async stopEntry(id: string): Promise<void> {
385
+ const runtime = this.runtimes.get(id)
386
+ if (runtime === undefined) return
387
+ this.runtimes.delete(id)
388
+ try {
389
+ if (runtime.isDisposed) return
390
+ await runtime.stop()
391
+ } catch (err) {
392
+ this.record(id, err)
393
+ } finally {
394
+ try {
395
+ await runtime.dispose()
396
+ } catch (err) {
397
+ this.record(id, err)
398
+ }
399
+ }
400
+ }
401
+
402
+ /**
403
+ * Release every runtime (plugin teardown / disable). Idempotent, and it keeps
404
+ * going after a failure so one wedged wiki cannot leave the others running.
405
+ */
406
+ async disposeAll(): Promise<void> {
407
+ for (const id of [...this.runtimes.keys()]) {
408
+ await this.stopEntry(id)
409
+ }
410
+ }
411
+
412
+ private record(id: string, err: unknown): void {
413
+ const message = err instanceof Error ? err.message : String(err)
414
+ this.errors.push({ id, message })
415
+ this.log(`知识库「${id}」:${message}`)
416
+ }
417
+ }