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
package/src/host/seeds.ts CHANGED
@@ -106,6 +106,30 @@ export interface SeedContext {
106
106
  * their wiki. Absent (headless callers) = false.
107
107
  */
108
108
  wechat?: boolean
109
+ /**
110
+ * The same-origin proxy base THIS wiki's TW frontend must use (v0.28.0):
111
+ * `/dsh-tiddlywiki/tw/` (the legacy bare path, single-wiki default) or
112
+ * `/dsh-tiddlywiki/tw/<id>/` (one knowledge base among several).
113
+ *
114
+ * It MUST be per wiki: TW builds every API URL from this tiddler, so a wiki
115
+ * whose value points at the legacy path while another wiki is the default
116
+ * would render one wiki's UI while reading and writing another's data.
117
+ *
118
+ * Absent (headless callers / older hosts) = the legacy path.
119
+ */
120
+ proxyBase?: string
121
+ }
122
+
123
+ /**
124
+ * Is this value a same-origin proxy base WE wrote — for this wiki or a sibling?
125
+ *
126
+ * Used to tell "our own stale value" (safe to update) from "a base the user
127
+ * deliberately chose" (never touched). Matches the bare legacy path and any
128
+ * `/dsh-tiddlywiki/tw/<id>/` form.
129
+ */
130
+ export function isOurProxyBase(value: string | undefined): boolean {
131
+ if (typeof value !== 'string') return false
132
+ return /^\/dsh-tiddlywiki\/tw\/(?:[a-z0-9][a-z0-9._-]{0,63}\/)?$/.test(value.trim())
109
133
  }
110
134
 
111
135
  /**
@@ -659,19 +683,25 @@ export const SEED_DEFS: SeedDef[] = [
659
683
  {
660
684
  check: async (ctx) => {
661
685
  // `run` (below) honors a USER-CHOSEN base: it only writes when the
662
- // value is missing or still the legacy default. The check must agree,
663
- // otherwise a deliberate custom host is reported as「缺失」.
686
+ // value is missing, still the legacy default, or one of OUR OWN bases
687
+ // for another wiki (see isOurProxyBase). The check must agree, otherwise
688
+ // a deliberate custom host is reported as「缺失」.
664
689
  //
665
690
  // Read WITHOUT swallowing (v0.19.0): the old bare `catch` turned any
666
691
  // transient failure into `present: false` — i.e. it reported the user's
667
692
  // deliberately customised base as「缺失」and invited the settings page's
668
693
  // 「重新初始化」to overwrite it. A failure propagates to checkAllSeeds,
669
694
  // which reports「检查失败」instead of a bogus missing state.
695
+ const desired = ctx.proxyBase ?? TW_PROXY_PATH
670
696
  const current = (await ctx.client.get(TW_WEB_HOST_TIDDLER))?.text?.trim()
671
697
  const present = typeof current === 'string' && current.length > 0 && current !== TW_WEB_HOST_DEFAULT
672
- const detail = present
673
- ? (current === TW_PROXY_PATH ? `已指向 ${TW_PROXY_PATH}` : `已指向自定义基址 ${current}(保留,不会覆盖)`)
674
- : `当前:${current ?? '(缺失)'},应为 ${TW_PROXY_PATH}`
698
+ const detail = !present
699
+ ? `当前:${current ?? '(缺失)'},应为 ${desired}`
700
+ : (current === desired
701
+ ? `已指向 ${desired}`
702
+ : (isOurProxyBase(current)
703
+ ? `已指向 ${current}(本库应改为 ${desired},下次启动会更新)`
704
+ : `已指向自定义基址 ${current}(保留,不会覆盖)`))
675
705
  return { id: 'tw-web-host', title: 'TW 前端 API 基址(同源代理)', description: '把 $:/config/tiddlyweb/host 指向 DSH 同源代理,嵌入式 TW 才能经 DSH origin 访问(远程访问模式的前提)。', present, removable: false, detail }
676
706
  },
677
707
  run: async (ctx, force) => {
@@ -680,13 +710,24 @@ export const SEED_DEFS: SeedDef[] = [
680
710
  // "missing" (that would overwrite a user's custom base).
681
711
  const tiddler = await ctx.client.get(TW_WEB_HOST_TIDDLER)
682
712
  const current = tiddler?.text?.trim()
683
- // Non-force keeps the ensure semantics: write only when missing or still
684
- // the legacy default (a user override pointing elsewhere is honored).
685
- if (!force && current !== undefined && current !== TW_WEB_HOST_DEFAULT) {
713
+ const desired = ctx.proxyBase ?? TW_PROXY_PATH
714
+ // Non-force keeps the ensure semantics: write only when the value is
715
+ // missing, still TW's own legacy default, or a proxy base WE wrote for
716
+ // a DIFFERENT wiki (v0.28.0: with several knowledge bases each one needs
717
+ // its own `/tw/<id>/`, or its embedded editor is proxied to a sibling —
718
+ // the page shows wiki A while every call reads and writes wiki B).
719
+ const replaceable = current === undefined || current.length === 0 || current === TW_WEB_HOST_DEFAULT || isOurProxyBase(current)
720
+ if (!force && !replaceable) {
686
721
  return { id: 'tw-web-host', ok: true, wrote: false, detail: '已指向自定义基址,未覆盖' }
687
722
  }
688
- await ctx.client.put({ title: TW_WEB_HOST_TIDDLER, text: TW_PROXY_PATH, type: 'text/plain', tags: [] })
689
- return { id: 'tw-web-host', ok: true, wrote: true, detail: force ? '已重新初始化(强制写回代理基址)' : '已写入代理基址' }
723
+ // Idempotent: an identical value is NOT rewritten. Every re-PUT bumps
724
+ // `modified` on disk, which is a git diff for a file whose content never
725
+ // changed (the v0.24.2 language-pin lesson, same shape).
726
+ if (!force && current === desired) {
727
+ return { id: 'tw-web-host', ok: true, wrote: false, detail: `已指向 ${desired}` }
728
+ }
729
+ await ctx.client.put({ title: TW_WEB_HOST_TIDDLER, text: desired, type: 'text/plain', tags: [] })
730
+ return { id: 'tw-web-host', ok: true, wrote: true, detail: force ? '已重新初始化(强制写回代理基址)' : `已写入代理基址 ${desired}` }
690
731
  } catch (err) {
691
732
  return { id: 'tw-web-host', ok: false, wrote: false, error: err instanceof Error ? err.message : String(err) }
692
733
  }
@@ -0,0 +1,154 @@
1
+ /**
2
+ * Per-SESSION knowledge-base scope (v0.28.0) — which wiki a conversation works on.
3
+ *
4
+ * WHY A FILE OUTSIDE EVERY WIKI
5
+ * -----------------------------
6
+ * Same reason as the registry and the legacy pointer: the answer must not live
7
+ * inside any single wiki (it would be unreadable while deciding which wiki to
8
+ * talk to) and it must SURVIVE a `dsh web` restart — sessions are durable, so
9
+ * "which knowledge base is this conversation using" has to be too.
10
+ *
11
+ * $DSH_HOME/dsh-tiddlywiki/sessions.json
12
+ * { "version": 1, "sessions": { "<sessionId>": { "wikiId": "work", "at": "…" } } }
13
+ *
14
+ * FAIL SOFT, NEVER LOUD
15
+ * ---------------------
16
+ * This is a PREFERENCE, not configuration: a missing, malformed or unreadable
17
+ * file simply means "no explicit scope" and every session falls back to the
18
+ * farm's default wiki. It therefore never blocks anything and never throws —
19
+ * unlike the registry, where a malformed file must be reported because it
20
+ * decides WHERE the data lives.
21
+ *
22
+ * Stale entries are pruned on write (`SESSION_SCOPE_MAX_AGE_MS`): sessions come
23
+ * and go, and this file has no other bound.
24
+ *
25
+ * @module dsh-tiddlywiki/host/session-scope
26
+ */
27
+ import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
28
+ import { dirname } from 'node:path'
29
+ import { dshHomePath } from '../sdk.ts'
30
+
31
+ /** Pointer-file schema version (bumped only on an incompatible change). */
32
+ export const SESSION_SCOPE_VERSION = 1
33
+
34
+ /** How long an untouched session→wiki mapping is kept (pruned on write). */
35
+ export const SESSION_SCOPE_MAX_AGE_MS = 90 * 24 * 60 * 60 * 1_000
36
+
37
+ /** Persisted shape. */
38
+ export interface SessionScopeState {
39
+ version: number
40
+ sessions: Record<string, { wikiId: string; at: string }>
41
+ }
42
+
43
+ /** Result of a read: usable mappings plus a non-fatal problem, if any. */
44
+ export interface SessionScopeReadResult {
45
+ /** sessionId → wikiId (malformed entries are skipped). */
46
+ scopes: Record<string, string>
47
+ error?: string
48
+ }
49
+
50
+ /** Default file: `$DSH_HOME/dsh-tiddlywiki/sessions.json`. */
51
+ export function defaultSessionScopeFile(): string {
52
+ return dshHomePath('dsh-tiddlywiki', 'sessions.json')
53
+ }
54
+
55
+ /**
56
+ * Is this a usable session id?
57
+ *
58
+ * Session ids reach here from HTTP (the GUI selector) and are used as JSON keys,
59
+ * so they are validated rather than trusted. The charset mirrors the one the
60
+ * session-summary route already enforces.
61
+ */
62
+ export function isSafeSessionId(id: unknown): id is string {
63
+ return typeof id === 'string' && /^[A-Za-z0-9._:-]{1,120}$/.test(id)
64
+ }
65
+
66
+ /** Is this a usable wiki id? (Shape only — the registry decides existence.) */
67
+ function isSafeWikiId(id: unknown): id is string {
68
+ return typeof id === 'string' && /^[a-z0-9][a-z0-9._-]{0,63}$/.test(id)
69
+ }
70
+
71
+ /** Drop mappings older than `maxAgeMs` (or with an unusable timestamp). */
72
+ export function pruneScopes(state: SessionScopeState, now: number, maxAgeMs: number = SESSION_SCOPE_MAX_AGE_MS): SessionScopeState {
73
+ const sessions: SessionScopeState['sessions'] = {}
74
+ for (const [sessionId, entry] of Object.entries(state.sessions)) {
75
+ const at = Date.parse(entry.at)
76
+ if (!Number.isFinite(at)) continue
77
+ if (now - at > maxAgeMs) continue
78
+ sessions[sessionId] = entry
79
+ }
80
+ return { version: SESSION_SCOPE_VERSION, sessions }
81
+ }
82
+
83
+ /** Parse a stored document into the loose shape, dropping anything unusable. */
84
+ function parseState(raw: string): { state?: SessionScopeState; error?: string } {
85
+ let parsed: unknown
86
+ try {
87
+ parsed = JSON.parse(raw)
88
+ } catch {
89
+ return { error: '会话作用域文件不是合法 JSON' }
90
+ }
91
+ if (typeof parsed !== 'object' || parsed === null) return { error: '会话作用域文件格式不对' }
92
+ const sessionsRaw = (parsed as { sessions?: unknown }).sessions
93
+ if (typeof sessionsRaw !== 'object' || sessionsRaw === null) return { error: '会话作用域文件缺少 sessions 字段' }
94
+ const sessions: SessionScopeState['sessions'] = {}
95
+ let skipped = 0
96
+ for (const [sessionId, value] of Object.entries(sessionsRaw as Record<string, unknown>)) {
97
+ if (!isSafeSessionId(sessionId)) { skipped += 1; continue }
98
+ const entry = value as { wikiId?: unknown; at?: unknown } | null
99
+ if (entry === null || typeof entry !== 'object' || !isSafeWikiId(entry.wikiId) || typeof entry.at !== 'string') { skipped += 1; continue }
100
+ sessions[sessionId] = { wikiId: entry.wikiId, at: entry.at }
101
+ }
102
+ return {
103
+ state: { version: SESSION_SCOPE_VERSION, sessions },
104
+ ...(skipped > 0 ? { error: `会话作用域文件里有 ${skipped} 条无效记录,已忽略` } : {}),
105
+ }
106
+ }
107
+
108
+ /**
109
+ * Read the mappings. Never throws: an unreadable/malformed file yields `{}` plus
110
+ * an explanation (the caller may log it; nothing depends on this file).
111
+ */
112
+ export async function readSessionScopes(file: string = defaultSessionScopeFile()): Promise<SessionScopeReadResult> {
113
+ let raw: string
114
+ try {
115
+ raw = await readFile(file, 'utf8')
116
+ } catch (err) {
117
+ const code = (err as NodeJS.ErrnoException).code
118
+ if (code === 'ENOENT') return { scopes: {} }
119
+ return { scopes: {}, error: `会话作用域文件读不到(${file}):${err instanceof Error ? err.message : String(err)}` }
120
+ }
121
+ const parsed = parseState(raw)
122
+ if (parsed.state === undefined) return { scopes: {}, ...(parsed.error !== undefined ? { error: parsed.error } : {}) }
123
+ const scopes: Record<string, string> = {}
124
+ for (const [sessionId, entry] of Object.entries(parsed.state.sessions)) scopes[sessionId] = entry.wikiId
125
+ return { scopes, ...(parsed.error !== undefined ? { error: parsed.error } : {}) }
126
+ }
127
+
128
+ /** Write the state atomically (tmp + rename, mkdir -p). */
129
+ export async function writeSessionScopes(state: SessionScopeState, file: string = defaultSessionScopeFile()): Promise<void> {
130
+ const payload = JSON.stringify({ ...state, updatedAt: new Date().toISOString() }, null, 2)
131
+ await mkdir(dirname(file), { recursive: true })
132
+ const tmp = `${file}.tmp`
133
+ await writeFile(tmp, payload, 'utf8')
134
+ await rename(tmp, file)
135
+ }
136
+
137
+ /**
138
+ * Point one session at a wiki, or clear its scope (`wikiId === undefined`).
139
+ *
140
+ * Reads, prunes and writes in one go — the file is tiny and this happens once
141
+ * per selection, so a read-modify-write is cheaper than any locking scheme.
142
+ * A write failure is REPORTED (the caller surfaces it) but changes nothing else:
143
+ * the session simply keeps falling back to the default.
144
+ */
145
+ export async function setSessionScope(sessionId: string, wikiId: string | undefined, file: string = defaultSessionScopeFile()): Promise<void> {
146
+ if (!isSafeSessionId(sessionId)) throw new Error(`会话 id 非法:${JSON.stringify(sessionId)}`)
147
+ if (wikiId !== undefined && !isSafeWikiId(wikiId)) throw new Error(`知识库 id 非法:${JSON.stringify(wikiId)}`)
148
+ const existing = await readFile(file, 'utf8').catch(() => '')
149
+ const parsed = existing.length > 0 ? (parseState(existing).state ?? { version: SESSION_SCOPE_VERSION, sessions: {} }) : { version: SESSION_SCOPE_VERSION, sessions: {} }
150
+ const pruned = pruneScopes(parsed, Date.now())
151
+ if (wikiId === undefined) delete pruned.sessions[sessionId]
152
+ else pruned.sessions[sessionId] = { wikiId, at: new Date().toISOString() }
153
+ await writeSessionScopes(pruned, file)
154
+ }
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Ship the "split my wiki" skill into the user's skill root (v0.28.0).
3
+ *
4
+ * WHY A SKILL, AND WHY HERE
5
+ * -------------------------
6
+ * The feature the plugin needs to explain — "how do I split my existing wiki into
7
+ * several" — is a multi-step conversation with a human, not a setting. DSH's
8
+ * container for exactly that is a skill: the agent loads it on demand, it costs
9
+ * nothing in the prompt budget when unused, and it lives in a directory the skill
10
+ * provider already scans (`$DSH_HOME/skills`).
11
+ *
12
+ * The plugin CANNOT register a skill root (a cordis patch cannot compute install
13
+ * paths), so the only zero-config path is writing the file into the user's root.
14
+ *
15
+ * NEVER CLOBBER ANYTHING THAT IS NOT OURS
16
+ * ---------------------------------------
17
+ * The shipped file carries a marker line (`dsh-tiddlywiki-skill:wiki-split`). This
18
+ * installer writes only when the target is MISSING, IDENTICAL (no-op), or OURS
19
+ * (marker present → update it). A file without the marker is left alone and the
20
+ * result says so — the alternative (overwriting whatever is at that path) would
21
+ * silently destroy a user's own skill the day they happen to pick our name.
22
+ *
23
+ * @module dsh-tiddlywiki/host/skill-install
24
+ */
25
+ import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
26
+ import { dirname, join } from 'node:path'
27
+ import { fileURLToPath } from 'node:url'
28
+ import { dshHomePath } from '../sdk.ts'
29
+
30
+ /** Directory name under the skill root (also the skill's stable identity). */
31
+ export const SPLIT_SKILL_DIR = 'dsh-tiddlywiki-wiki-split'
32
+
33
+ /** File name inside that directory (the skill provider's discovery contract). */
34
+ export const SKILL_FILE_NAME = 'SKILL.md'
35
+
36
+ /**
37
+ * Marker proving a file at our target path is OURS. Present in the shipped
38
+ * SKILL.md; a user who edits the skill can delete the line to take ownership
39
+ * (and then the installer will never touch it again).
40
+ */
41
+ export const SPLIT_SKILL_MARKER = 'dsh-tiddlywiki-skill:wiki-split'
42
+
43
+ /** Where the file lives once installed: `$DSH_HOME/skills/<dir>/SKILL.md`. */
44
+ export function defaultSkillRoot(): string {
45
+ return dshHomePath('skills')
46
+ }
47
+
48
+ export interface SkillInstallResult {
49
+ path: string
50
+ /** `written` = created, `updated` = ours and changed, `kept` = left alone. */
51
+ action: 'written' | 'updated' | 'kept' | 'failed'
52
+ detail?: string
53
+ error?: string
54
+ }
55
+
56
+ /**
57
+ * Read the skill that ships inside this package.
58
+ *
59
+ * Two candidates because the same module runs from two places: `lib/index.js`
60
+ * (published / loaded) has `skills/` as a SIBLING, while `src/host/*.ts` (tests
61
+ * via tsx) sits two levels down. Returns undefined when neither exists.
62
+ */
63
+ export async function readBundledSkillText(): Promise<string | undefined> {
64
+ for (const url of [
65
+ new URL('../skills/wiki-split/SKILL.md', import.meta.url),
66
+ new URL('../../skills/wiki-split/SKILL.md', import.meta.url),
67
+ ]) {
68
+ try {
69
+ return await readFile(fileURLToPath(url), 'utf8')
70
+ } catch {
71
+ /* try the next candidate */
72
+ }
73
+ }
74
+ return undefined
75
+ }
76
+
77
+ /**
78
+ * Install (or refresh) the split-wiki skill. Never throws: every problem comes
79
+ * back as `action: 'failed'` with a message, because a skill that could not be
80
+ * written must not take the plugin's startup down with it.
81
+ */
82
+ export async function installSplitSkill(options: {
83
+ /** Skill root (defaults to `$DSH_HOME/skills`). */
84
+ root?: string
85
+ /** The text to install (defaults to the file shipped in this package). */
86
+ text?: string
87
+ } = {}): Promise<SkillInstallResult> {
88
+ const root = options.root ?? defaultSkillRoot()
89
+ const path = join(root, SPLIT_SKILL_DIR, SKILL_FILE_NAME)
90
+ const text = options.text ?? await readBundledSkillText()
91
+ if (text === undefined || text.trim().length === 0) {
92
+ return { path, action: 'failed', error: '找不到随包提供的 SKILL.md(package 里缺 skills/wiki-split/SKILL.md)' }
93
+ }
94
+ let existing: string | undefined
95
+ try {
96
+ existing = await readFile(path, 'utf8')
97
+ } catch (err) {
98
+ if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
99
+ return { path, action: 'failed', error: `读不到 ${path}:${err instanceof Error ? err.message : String(err)}` }
100
+ }
101
+ }
102
+
103
+ if (existing !== undefined) {
104
+ if (existing === text) return { path, action: 'kept', detail: '已是最新' }
105
+ if (!existing.includes(SPLIT_SKILL_MARKER)) {
106
+ return { path, action: 'kept', detail: '该路径已有你自己的文件(没有插件标记),未覆盖' }
107
+ }
108
+ }
109
+
110
+ try {
111
+ await mkdir(dirname(path), { recursive: true })
112
+ const tmp = `${path}.tmp`
113
+ await writeFile(tmp, text, 'utf8')
114
+ await rename(tmp, path)
115
+ } catch (err) {
116
+ return { path, action: 'failed', error: err instanceof Error ? err.message : String(err) }
117
+ }
118
+ return existing === undefined
119
+ ? { path, action: 'written', detail: '已安装「拆分知识库」skill' }
120
+ : { path, action: 'updated', detail: '已更新到随包版本' }
121
+ }