dsh-tiddlywiki 0.2.1 → 0.3.0

package/src/host/config.ts

@@ -25,6 +25,8 @@ export interface PluginConfigShape {
     showQuickNote?: boolean
     /** 是否显示 TW 面板右下角的「状态/重载」悬浮按钮（默认 true）。 */
     showPanelStatus?: boolean
+    /** 是否在界面右下角显示「同步」悬浮按钮（默认 true）。 */
+    showSyncButton?: boolean
   }
   uiLanguage?: string
   [key: string]: unknown

package/src/host/git.ts

@@ -118,10 +118,20 @@ export class GitFace {
     return { exists: true, branch, dirty, dirtyFiles, remote, ...(lastCommit !== undefined ? { lastCommit } : {}), ...(ahead !== undefined ? { ahead } : {}), ...(behind !== undefined ? { behind } : {}) }
   }
 
-  /** `git pull --rebase --autostash`; on conflict: abort + report files. */
-  async pull(dir: string): Promise<GitActionResult> {
+  /** `git pull --rebase --autostash`; on conflict: abort + report files.
+   *  On success, `changed: true` means HEAD actually moved (files came in /
+   *  commits were replayed) — callers use it to decide whether a running TW
+   *  child needs a restart to drop its stale in-memory snapshot. */
+  async pull(dir: string): Promise<GitActionResult & { changed?: boolean }> {
+    const before = await this.exec(['rev-parse', 'HEAD'], { cwd: dir, timeout: QUICK_TIMEOUT_MS })
+    const beforeHead = before.ok ? before.stdout.trim() : ''
     const r = await this.exec(['pull', '--rebase', '--autostash'], { cwd: dir, timeout: HEAVY_TIMEOUT_MS })
-    if (r.ok) return { ok: true, message: r.stdout.trim() || 'pull ok' }
+    if (r.ok) {
+      const after = await this.exec(['rev-parse', 'HEAD'], { cwd: dir, timeout: QUICK_TIMEOUT_MS })
+      const afterHead = after.ok ? after.stdout.trim() : ''
+      const changed = beforeHead.length > 0 && beforeHead !== afterHead
+      return { ok: true, message: r.stdout.trim() || 'pull ok', ...(changed ? { changed: true } : {}) }
+    }
     const conflictFiles = await this.unmergedFiles(dir)
     await this.exec(['rebase', '--abort'], { cwd: dir, timeout: HEAVY_TIMEOUT_MS })
     const reason = (r.stderr.trim() || r.stdout.trim()).slice(0, 500)

package/src/host/routes.ts

@@ -15,6 +15,8 @@
  * @module dsh-tiddlywiki/host/routes
  */
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import { mkdir, writeFile, access } from 'node:fs/promises'
+import { basename, extname, join } from 'node:path'
 import type { TiddlyWebClient } from './tw-api.ts'
 import type { WikiServer } from './wiki.ts'
 import type { GitFace } from './git.ts'
@@ -28,18 +30,28 @@ const MAX_BODY_BYTES = 2 * 1024 * 1024
 /** Max passthrough body (tiddler content can be large). */
 const MAX_PROXY_BODY_BYTES = 16 * 1024 * 1024
 
+/** Max uploaded file body. */
+const MAX_UPLOAD_BYTES = 64 * 1024 * 1024
+
 /** Structural webserver face (a subset of dsh-host-webserver). */
 export interface WebServerFace {
   register(route: { kind: 'exact' | 'prefix'; path: string; handler: (req: IncomingMessage, res: ServerResponse) => void }): () => void
 }
 
+/** Effective UI visibility flags returned by /status (mirror index.ts). */
+export interface UiDefaultsPublic {
+  showQuickNote: boolean
+  showPanelStatus: boolean
+  showSyncButton: boolean
+}
+
 export interface RouteDeps {
   server: WikiServer
   getClient: () => TiddlyWebClient | undefined
   git: GitFace
   autoCommit: () => void
   noteDefaults: () => { tag: string }
-  uiDefaults: () => { showQuickNote: boolean; showPanelStatus: boolean }
+  uiDefaults: () => UiDefaultsPublic
   getWikiPath: () => string
 }
 
@@ -61,6 +73,41 @@ function readBody(req: IncomingMessage, limit = MAX_BODY_BYTES): Promise<string>
   })
 }
 
+/** Read a raw (binary-safe) request body up to `limit` bytes. */
+function readBodyBuffer(req: IncomingMessage, limit = MAX_UPLOAD_BYTES): Promise<Buffer> {
+  return new Promise((resolveP, rejectP) => {
+    let size = 0
+    const chunks: Buffer[] = []
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length
+      if (size > limit) {
+        rejectP(new Error('file too large'))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => resolveP(Buffer.concat(chunks)))
+    req.on('error', rejectP)
+  })
+}
+
+/**
+ * Sanitize an uploaded filename into a safe bare name (no path separators,
+ * no `..`, no control characters). Returns '' when nothing usable remains.
+ */
+function sanitizeUploadName(input: unknown): string {
+  if (typeof input !== 'string') return ''
+  const name = basename(input.trim().replace(/[\\/]+/g, '/'))
+    .replace(/[\u0000-\u001f\u007f]/g, '')
+    .replace(/[<>:"|?*]/g, '_')
+    .replace(/^\.+/, '')
+    .trim()
+  if (name.length === 0 || name === '.' || name === '..') return ''
+  if (name.length > 160) return name.slice(0, 160)
+  return name
+}
+
 function json(res: ServerResponse, payload: unknown, status = 200): void {
   const body = JSON.stringify(payload)
   res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
@@ -216,6 +263,107 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
     }
   }
 
+  /** One-click git sync for the floating button / settings page: pull →
+   *  commit → push, then return the fresh status. Mirrors the agent tool's
+   *  `action=sync` (design doc §7 conflict policy — rebase conflict aborts).
+   *  When the pull actually changed the working tree, the running TW child
+   *  still holds the old in-memory snapshot — restart it (same port) so the
+   *  UI reflects the pulled files instead of looking stale. */
+  const handleSync = async (_req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    const dir = deps.getWikiPath()
+    const status = async (): Promise<GitStatusViewPublic | null> => {
+      try { return await deps.git.status(dir) } catch { return null }
+    }
+    try {
+      const pulled = await deps.git.pull(dir)
+      if (!pulled.ok) {
+        json(res, {
+          ok: false,
+          action: 'sync',
+          message: pulled.message,
+          ...(pulled.conflictFiles !== undefined ? { conflictFiles: pulled.conflictFiles } : {}),
+          status: await status(),
+        }, 409)
+        return
+      }
+      let restarted = false
+      let restartError: string | undefined
+      if (pulled.changed === true) {
+        try {
+          await deps.server.restart()
+          restarted = true
+        } catch (err) {
+          restartError = err instanceof Error ? err.message : String(err)
+        }
+      }
+      const committed = await deps.git.commit(dir, `sync ${new Date().toISOString()}`)
+      const pushed = await deps.git.push(dir)
+      const fresh = await status()
+      json(res, {
+        ok: pushed.ok,
+        action: 'sync',
+        message: pushed.ok ? '同步完成' : pushed.message,
+        pull: 'ok',
+        ...(pulled.changed === true ? { changed: true } : {}),
+        restarted,
+        ...(restartError !== undefined ? { restartError } : {}),
+        commit: committed.message,
+        push: pushed.message,
+        status: fresh,
+        lastSync: new Date().toISOString(),
+      }, pushed.ok ? 200 : 502)
+    } catch (err) {
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+    }
+  }
+
+  /**
+   * Save an uploaded file into the wiki's `files/` folder (git-tracked; TW's
+   * core server serves it at `/files/<name>`, get-file.js — no restart
+   * needed). Body is the raw file; the name arrives in `X-Filename`. A
+   * collision appends `-1`, `-2`, … so nothing is ever overwritten.
+   */
+  const handleUpload = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    try {
+      const buf = await readBodyBuffer(req)
+      // Name comes from ?name= (URL-encoded) or the X-Filename header.
+      const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+      const nameParam = url.searchParams.get('name')
+      let name = sanitizeUploadName(nameParam ?? '')
+      if (name.length === 0 && typeof req.headers['x-filename'] === 'string') {
+        let decoded = ''
+        try { decoded = decodeURIComponent(req.headers['x-filename'] as string) } catch { decoded = req.headers['x-filename'] as string }
+        name = sanitizeUploadName(decoded)
+      }
+      if (name.length === 0) {
+        json(res, { ok: false, error: 'missing or invalid filename' }, 400)
+        return
+      }
+      const filesDir = join(deps.getWikiPath(), 'files')
+      await mkdir(filesDir, { recursive: true })
+      const ext = extname(name)
+      const stem = ext.length > 0 ? name.slice(0, -ext.length) : name
+      // Collision avoidance: files/some.txt, files/some-1.txt, …
+      let candidate = name
+      for (let i = 1; ; i++) {
+        try { await access(join(filesDir, candidate)) } catch { break }
+        candidate = `${stem}-${i}${ext}`
+      }
+      await writeFile(join(filesDir, candidate), buf)
+      deps.autoCommit()
+      json(res, {
+        ok: true,
+        name: candidate,
+        path: `files/${candidate}`,
+        url: `/files/${encodeURIComponent(candidate)}`,
+        size: buf.length,
+        type: req.headers['content-type'] ?? 'application/octet-stream',
+      })
+    } catch (err) {
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, err instanceof Error && /too large/.test(err.message) ? 413 : 500)
+    }
+  }
+
   /** Passthrough /dsh-tiddlywiki/api/<rest> → TW root /<rest>. */
   const handleApiProxy = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     const client = deps.getClient()
@@ -251,6 +399,8 @@ export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDep
     ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/note`, handler: (req, res) => { void handleNote(req, res) } }),
     ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/edit`, handler: (req, res) => { void handleEdit(req, res) } }),
     ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/tags`, handler: (req, res) => { void handleTags(req, res) } }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/sync`, handler: (req, res) => { void handleSync(req, res) } }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/upload`, handler: (req, res) => { void handleUpload(req, res) } }),
     ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/restart`, handler: (req, res) => { void handleRestart(req, res) } }),
     ctx.webServer.register({ kind: 'prefix', path: `${ROUTE_PREFIX}/api`, handler: (req, res) => { void handleApiProxy(req, res) } }),
   ]

package/src/host/tools.ts

@@ -27,6 +27,10 @@ export interface ToolsDeps {
   noteTag: () => string
   /** Debounced auto-commit touch (fires after our writes). */
   autoCommit: () => void
+  /** Restart the TW child (same port). Called after a pull that changed the
+   *  working tree, so the server drops its stale in-memory snapshot and the
+   *  agent sees the pulled content. Optional — absent in headless contexts. */
+  restartWiki?: () => Promise<void>
 }
 
 function snippetOf(text: string, max = 160): string {
@@ -180,10 +184,21 @@ export function registerTiddlywikiTools(ctx: ToolsCtx, deps: ToolsDeps): Array<(
     },
     execute: async (args: { action: 'pull' | 'push' | 'sync'; message?: string }): Promise<SyncResult> => {
       const dir = deps.wikiPath()
+      /** Restart TW after a pull that changed the tree (stale snapshot drop). */
+      const restartIfChanged = async (pulled: { changed?: boolean }): Promise<{ restarted?: boolean; restartError?: string }> => {
+        if (pulled.changed !== true || deps.restartWiki === undefined) return {}
+        try {
+          await deps.restartWiki()
+          return { restarted: true }
+        } catch (err) {
+          return { restartError: err instanceof Error ? err.message : String(err) }
+        }
+      }
       switch (args.action) {
         case 'pull': {
           const r = await deps.git.pull(dir)
-          return { action: args.action, ok: r.ok, message: r.message, ...(r.conflictFiles !== undefined ? { conflictFiles: r.conflictFiles } : {}) }
+          const restart = await restartIfChanged(r)
+          return { action: args.action, ok: r.ok, message: r.message, ...(r.conflictFiles !== undefined ? { conflictFiles: r.conflictFiles } : {}), ...(r.changed === true ? { changed: true } : {}), ...restart }
         }
         case 'push': {
           const r = await deps.git.push(dir)
@@ -192,6 +207,7 @@ export function registerTiddlywikiTools(ctx: ToolsCtx, deps: ToolsDeps): Array<(
         case 'sync': {
           const pulled = await deps.git.pull(dir)
           if (!pulled.ok) return { action: args.action, ok: false, message: pulled.message, ...(pulled.conflictFiles !== undefined ? { conflictFiles: pulled.conflictFiles } : {}) }
+          const restart = await restartIfChanged(pulled)
           const committed = await deps.git.commit(dir, args.message ?? `sync ${new Date().toISOString()}`)
           const pushed = await deps.git.push(dir)
           const status = await deps.git.status(dir)
@@ -200,6 +216,8 @@ export function registerTiddlywikiTools(ctx: ToolsCtx, deps: ToolsDeps): Array<(
             ok: pushed.ok,
             message: pushed.ok ? '同步完成' : pushed.message,
             pull: 'ok',
+            ...(pulled.changed === true ? { changed: true } : {}),
+            ...restart,
             commit: committed.message,
             push: pushed.message,
             status,
@@ -227,6 +245,9 @@ interface SyncResult {
   pull?: string
   commit?: string
   push?: string
+  changed?: boolean
+  restarted?: boolean
+  restartError?: string
   status?: { branch: string; dirty: boolean; dirtyFiles: string[]; remote: string; lastCommit?: string; ahead?: number; behind?: number }
 }
 
@@ -240,6 +261,12 @@ function renderSync(value: SyncResult): Array<{ type: 'text'; text: string }> {
   }
   if (value.commit !== undefined) lines.push(`本地 commit: ${value.commit}`)
   if (value.push !== undefined) lines.push(`远端 push: ${value.push}`)
+  if (value.changed === true) {
+    lines.push(value.restarted === true
+      ? '本次 pull 拉取了新内容，TW 服务已自动重启（同端口），读取/搜索均为最新快照。'
+      : '本次 pull 拉取了新内容，但 TW 服务未能自动重启（如需最新快照，请手动重启 TW）。')
+  }
+  if (value.restartError !== undefined) lines.push(`TW 重启失败: ${value.restartError}`)
   if (value.status !== undefined) {
     const s = value.status
     const bits = [`分支 ${s.branch}`]

package/src/host/tw-api.ts

@@ -1,157 +1,157 @@
-/**
- * TiddlyWeb REST client (design doc §5) — the ONLY way every writer reaches
- * the wiki (quick notes, agent tools, editor saves all go through the TW
- * service, D1), so there is never a second write path.
- *
- * ROUTES ARE EMPIRICALLY VERIFIED against tiddlywiki 5.4.1's core-server
- * (`core-server/server/routes/`):
- *   GET    /recipes/default/tiddlers.json[?exclude=...]  list (skinny)
- *   GET    /recipes/default/tiddlers/<title>             read one (404 absent)
- *   PUT    /recipes/default/tiddlers/<title>             write one (204)
- *   DELETE /bags/default/tiddlers/<title>                delete one (204)
- * Writes require the `X-Requested-With: TiddlyWiki` header (TW CSRF), which
- * this client always sends. Tags arrive as a whitespace-joined STRING and are
- * normalized to arrays here.
- *
- * SEARCH (R2): the server blocks arbitrary `filter=` queries with 403 unless
- * the exact filter is whitelisted in $:/config/Server/ExternalFilters. So
- * `search()` fetches the default listing WITH text (`?exclude=` a sentinel)
- * and matches locally — one request, no 403, no per-tiddler round-trips.
- *
- * @module dsh-tiddlywiki/host/tw-api
- */
-
-/** A tiddler's readable fields (loose on purpose). */
-export interface Tiddler {
-  title: string
-  text?: string
-  tags?: string[]
-  type?: string
-  created?: string
-  modified?: string
-  /** Extra custom fields returned by the server are folded under `fields`. */
-  fields?: Record<string, unknown>
-  [key: string]: unknown
-}
-
-const REQUEST_TIMEOUT_MS = 10_000
-
-/** TW's CSRF gate: writes must carry this header (TW's own UI always does). */
-const CSRF_HEADER = { 'x-requested-with': 'TiddlyWiki' }
-
-/** Sentinel `exclude` value: excludes nothing, so `text` stays in the list. */
-const LIST_WITH_TEXT_EXCLUDE = '__dsh_tw_none__'
-
-/** Split TW's whitespace-joined tags string into an array. */
-function normalizeTags(tags: unknown): string[] | undefined {
-  if (tags === undefined) return undefined
-  if (Array.isArray(tags)) return tags.map(String)
-  if (typeof tags === 'string') {
-    const parts = tags.trim().split(/\s+/).filter(Boolean)
-    return parts.length > 0 ? parts : []
-  }
-  return []
-}
-
-/** Normalize a raw server tiddler (tags string → array, unknown fields nested). */
-function normalizeTiddler(raw: Record<string, unknown>): Tiddler {
-  const out = { ...raw } as Tiddler
-  const tags = normalizeTags(raw.tags)
-  if (tags !== undefined) out.tags = tags
-  return out
-}
-
-export class TiddlyWebClient {
-  constructor(private readonly baseUrl: string) {}
-
-  private async request(path: string, init?: RequestInit): Promise<Response> {
-    return fetch(`${this.baseUrl}${path}`, {
-      ...init,
-      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-    })
-  }
-
-  /** GET /status → { username, anonymous, space, tiddlywiki_version, ... }. */
-  async status(): Promise<Record<string, unknown>> {
-    const res = await this.request('/status')
-    if (!res.ok) throw new Error(`TiddlyWeb /status HTTP ${res.status}`)
-    return res.json() as Promise<Record<string, unknown>>
-  }
-
-  /** Read one tiddler; undefined when it does not exist (404). */
-  async get(title: string): Promise<Tiddler | undefined> {
-    const res = await this.request(`/recipes/default/tiddlers/${encodeURIComponent(title)}`)
-    if (res.status === 404) return undefined
-    if (!res.ok) throw new Error(`TiddlyWeb GET /recipes/default/tiddlers/${title} HTTP ${res.status}`)
-    return normalizeTiddler((await res.json()) as Record<string, unknown>)
-  }
-
-  /** Write (create or overwrite) one tiddler via PUT (204 on success). */
-  async put(tiddler: Tiddler): Promise<Tiddler> {
-    const title = tiddler.title
-    const res = await this.request(`/recipes/default/tiddlers/${encodeURIComponent(title)}`, {
-      method: 'PUT',
-      headers: { 'content-type': 'application/json', ...CSRF_HEADER },
-      body: JSON.stringify(tiddler),
-    })
-    if (!res.ok) {
-      const detail = await res.text().catch(() => '')
-      throw new Error(`TiddlyWeb PUT /recipes/default/tiddlers/${title} HTTP ${res.status}: ${detail.slice(0, 300)}`)
-    }
-    return tiddler
-  }
-
-  /** Delete one tiddler via the bags route (204); a missing one is a no-op. */
-  async delete(title: string): Promise<void> {
-    const res = await this.request(`/bags/default/tiddlers/${encodeURIComponent(title)}`, {
-      method: 'DELETE',
-      headers: CSRF_HEADER,
-    })
-    if (res.status === 404) return
-    if (!res.ok) throw new Error(`TiddlyWeb DELETE /bags/default/tiddlers/${title} HTTP ${res.status}`)
-  }
-
-  /**
-   * List tiddlers via the default server filter. Arbitrary `filter=` queries
-   * are blocked by the server (403) unless whitelisted, so callers needing a
-   * subset should use search(); a supplied filter that is 403-blocked falls
-   * back to the default listing.
-   */
-  async list(filter?: string, includeText = false): Promise<Tiddler[]> {
-    const params = new URLSearchParams()
-    if (includeText) params.set('exclude', LIST_WITH_TEXT_EXCLUDE)
-    if (filter !== undefined && filter.length > 0) params.set('filter', filter)
-    const query = params.toString()
-    let res = await this.request(`/recipes/default/tiddlers.json${query.length > 0 ? `?${query}` : ''}`)
-    if (!res.ok && res.status === 403 && filter !== undefined && filter.length > 0) {
-      // Filter not whitelisted → refetch with the default filter.
-      const retry = new URLSearchParams()
-      if (includeText) retry.set('exclude', LIST_WITH_TEXT_EXCLUDE)
-      const retryQuery = retry.toString()
-      res = await this.request(`/recipes/default/tiddlers.json${retryQuery.length > 0 ? `?${retryQuery}` : ''}`)
-    }
-    if (!res.ok) throw new Error(`TiddlyWeb recipe list HTTP ${res.status}`)
-    const data = (await res.json()) as Array<Record<string, unknown>> | { tiddlers?: Array<Record<string, unknown>> }
-    const items = Array.isArray(data) ? data : (data.tiddlers ?? [])
-    return items.map(normalizeTiddler)
-  }
-
-  /**
-   * Search non-system tiddlers: one request (default listing with text) plus
-   * local case-insensitive substring matching on title + text, optional exact
-   * tag, capped at `limit`. Robust against the server's external-filter 403.
-   */
-  async search(query: string, tag?: string, limit = 30): Promise<Tiddler[]> {
-    const items = await this.list(undefined, true)
-    const needle = query.toLowerCase()
-    const matched = items.filter((t) => {
-      if (!t.title.toLowerCase().includes(needle) && !(t.text ?? '').toLowerCase().includes(needle)) return false
-      if (tag !== undefined && tag.length > 0) {
-        const tags = t.tags ?? []
-        if (!tags.some((t2) => t2.toLowerCase() === tag.toLowerCase())) return false
-      }
-      return true
-    })
-    return matched.slice(0, limit)
-  }
-}
+/**
+ * TiddlyWeb REST client (design doc §5) — the ONLY way every writer reaches
+ * the wiki (quick notes, agent tools, editor saves all go through the TW
+ * service, D1), so there is never a second write path.
+ *
+ * ROUTES ARE EMPIRICALLY VERIFIED against tiddlywiki 5.4.1's core-server
+ * (`core-server/server/routes/`):
+ *   GET    /recipes/default/tiddlers.json[?exclude=...]  list (skinny)
+ *   GET    /recipes/default/tiddlers/<title>             read one (404 absent)
+ *   PUT    /recipes/default/tiddlers/<title>             write one (204)
+ *   DELETE /bags/default/tiddlers/<title>                delete one (204)
+ * Writes require the `X-Requested-With: TiddlyWiki` header (TW CSRF), which
+ * this client always sends. Tags arrive as a whitespace-joined STRING and are
+ * normalized to arrays here.
+ *
+ * SEARCH (R2): the server blocks arbitrary `filter=` queries with 403 unless
+ * the exact filter is whitelisted in $:/config/Server/ExternalFilters. So
+ * `search()` fetches the default listing WITH text (`?exclude=` a sentinel)
+ * and matches locally — one request, no 403, no per-tiddler round-trips.
+ *
+ * @module dsh-tiddlywiki/host/tw-api
+ */
+
+/** A tiddler's readable fields (loose on purpose). */
+export interface Tiddler {
+  title: string
+  text?: string
+  tags?: string[]
+  type?: string
+  created?: string
+  modified?: string
+  /** Extra custom fields returned by the server are folded under `fields`. */
+  fields?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+const REQUEST_TIMEOUT_MS = 10_000
+
+/** TW's CSRF gate: writes must carry this header (TW's own UI always does). */
+const CSRF_HEADER = { 'x-requested-with': 'TiddlyWiki' }
+
+/** Sentinel `exclude` value: excludes nothing, so `text` stays in the list. */
+const LIST_WITH_TEXT_EXCLUDE = '__dsh_tw_none__'
+
+/** Split TW's whitespace-joined tags string into an array. */
+function normalizeTags(tags: unknown): string[] | undefined {
+  if (tags === undefined) return undefined
+  if (Array.isArray(tags)) return tags.map(String)
+  if (typeof tags === 'string') {
+    const parts = tags.trim().split(/\s+/).filter(Boolean)
+    return parts.length > 0 ? parts : []
+  }
+  return []
+}
+
+/** Normalize a raw server tiddler (tags string → array, unknown fields nested). */
+function normalizeTiddler(raw: Record<string, unknown>): Tiddler {
+  const out = { ...raw } as Tiddler
+  const tags = normalizeTags(raw.tags)
+  if (tags !== undefined) out.tags = tags
+  return out
+}
+
+export class TiddlyWebClient {
+  constructor(private readonly baseUrl: string) {}
+
+  private async request(path: string, init?: RequestInit): Promise<Response> {
+    return fetch(`${this.baseUrl}${path}`, {
+      ...init,
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    })
+  }
+
+  /** GET /status → { username, anonymous, space, tiddlywiki_version, ... }. */
+  async status(): Promise<Record<string, unknown>> {
+    const res = await this.request('/status')
+    if (!res.ok) throw new Error(`TiddlyWeb /status HTTP ${res.status}`)
+    return res.json() as Promise<Record<string, unknown>>
+  }
+
+  /** Read one tiddler; undefined when it does not exist (404). */
+  async get(title: string): Promise<Tiddler | undefined> {
+    const res = await this.request(`/recipes/default/tiddlers/${encodeURIComponent(title)}`)
+    if (res.status === 404) return undefined
+    if (!res.ok) throw new Error(`TiddlyWeb GET /recipes/default/tiddlers/${title} HTTP ${res.status}`)
+    return normalizeTiddler((await res.json()) as Record<string, unknown>)
+  }
+
+  /** Write (create or overwrite) one tiddler via PUT (204 on success). */
+  async put(tiddler: Tiddler): Promise<Tiddler> {
+    const title = tiddler.title
+    const res = await this.request(`/recipes/default/tiddlers/${encodeURIComponent(title)}`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json', ...CSRF_HEADER },
+      body: JSON.stringify(tiddler),
+    })
+    if (!res.ok) {
+      const detail = await res.text().catch(() => '')
+      throw new Error(`TiddlyWeb PUT /recipes/default/tiddlers/${title} HTTP ${res.status}: ${detail.slice(0, 300)}`)
+    }
+    return tiddler
+  }
+
+  /** Delete one tiddler via the bags route (204); a missing one is a no-op. */
+  async delete(title: string): Promise<void> {
+    const res = await this.request(`/bags/default/tiddlers/${encodeURIComponent(title)}`, {
+      method: 'DELETE',
+      headers: CSRF_HEADER,
+    })
+    if (res.status === 404) return
+    if (!res.ok) throw new Error(`TiddlyWeb DELETE /bags/default/tiddlers/${title} HTTP ${res.status}`)
+  }
+
+  /**
+   * List tiddlers via the default server filter. Arbitrary `filter=` queries
+   * are blocked by the server (403) unless whitelisted, so callers needing a
+   * subset should use search(); a supplied filter that is 403-blocked falls
+   * back to the default listing.
+   */
+  async list(filter?: string, includeText = false): Promise<Tiddler[]> {
+    const params = new URLSearchParams()
+    if (includeText) params.set('exclude', LIST_WITH_TEXT_EXCLUDE)
+    if (filter !== undefined && filter.length > 0) params.set('filter', filter)
+    const query = params.toString()
+    let res = await this.request(`/recipes/default/tiddlers.json${query.length > 0 ? `?${query}` : ''}`)
+    if (!res.ok && res.status === 403 && filter !== undefined && filter.length > 0) {
+      // Filter not whitelisted → refetch with the default filter.
+      const retry = new URLSearchParams()
+      if (includeText) retry.set('exclude', LIST_WITH_TEXT_EXCLUDE)
+      const retryQuery = retry.toString()
+      res = await this.request(`/recipes/default/tiddlers.json${retryQuery.length > 0 ? `?${retryQuery}` : ''}`)
+    }
+    if (!res.ok) throw new Error(`TiddlyWeb recipe list HTTP ${res.status}`)
+    const data = (await res.json()) as Array<Record<string, unknown>> | { tiddlers?: Array<Record<string, unknown>> }
+    const items = Array.isArray(data) ? data : (data.tiddlers ?? [])
+    return items.map(normalizeTiddler)
+  }
+
+  /**
+   * Search non-system tiddlers: one request (default listing with text) plus
+   * local case-insensitive substring matching on title + text, optional exact
+   * tag, capped at `limit`. Robust against the server's external-filter 403.
+   */
+  async search(query: string, tag?: string, limit = 30): Promise<Tiddler[]> {
+    const items = await this.list(undefined, true)
+    const needle = query.toLowerCase()
+    const matched = items.filter((t) => {
+      if (!t.title.toLowerCase().includes(needle) && !(t.text ?? '').toLowerCase().includes(needle)) return false
+      if (tag !== undefined && tag.length > 0) {
+        const tags = t.tags ?? []
+        if (!tags.some((t2) => t2.toLowerCase() === tag.toLowerCase())) return false
+      }
+      return true
+    })
+    return matched.slice(0, limit)
+  }
+}