dsh-tiddlywiki 0.1.0

package/src/host/config.ts

@@ -0,0 +1,86 @@
+/**
+ * Extensible plugin config (design doc §13, config panel).
+ *
+ * Two layers:
+ *   base      — the cordis `config:` block (profile composition, defaults);
+ *   overrides — a user-editable config tiddler ($:/plugins/dsh-tiddlywiki/config,
+ *               a JSON string) written by the settings page.
+ * The tiddler overlays the base (tiddler wins), so future config fields just
+ * extend the shape — no schema, no @deepseek-ai dependency, and the config
+ * travels with the wiki's git history.
+ *
+ * @module dsh-tiddlywiki/host/config
+ */
+import type { TiddlyWebClient } from './tw-api.ts'
+
+/** Config tiddler (JSON string) where the settings page stores overrides. */
+export const CONFIG_TIDDLER = '$:/plugins/dsh-tiddlywiki/config'
+
+/** Extensible, loose plugin config shape (future fields just appear here). */
+export interface PluginConfigShape {
+  note?: { tag?: string }
+  git?: { autoCommit?: boolean; debounceMs?: number; remote?: string; branch?: string }
+  uiLanguage?: string
+  [key: string]: unknown
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Deep-merge: `over` wins; nested plain objects merge recursively. */
+export function deepMerge(base: Record<string, unknown>, over: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...base }
+  for (const [key, value] of Object.entries(over)) {
+    if (value === undefined) continue
+    if (isPlainObject(value) && isPlainObject(out[key])) {
+      out[key] = deepMerge(out[key] as Record<string, unknown>, value)
+    } else {
+      out[key] = value
+    }
+  }
+  return out
+}
+
+/**
+ * Runtime config store: caches the override tiddler and exposes the effective
+ * (merged) config. `load` runs at startup and after every write/restart.
+ */
+export class ConfigStore {
+  private overrides: PluginConfigShape = {}
+
+  constructor(private readonly base: PluginConfigShape) {}
+
+  /** Effective config = cordis base overlaid with the user override tiddler. */
+  get(): PluginConfigShape {
+    return deepMerge(this.base, this.overrides) as PluginConfigShape
+  }
+
+  /** Reload the override tiddler (no-op when the wiki is unavailable). */
+  async load(client: TiddlyWebClient | undefined): Promise<void> {
+    this.overrides = {}
+    if (client === undefined) return
+    try {
+      const tiddler = await client.get(CONFIG_TIDDLER)
+      if (tiddler !== undefined && typeof tiddler.text === 'string') {
+        const parsed = JSON.parse(tiddler.text) as unknown
+        if (isPlainObject(parsed)) this.overrides = parsed as PluginConfigShape
+      }
+    } catch {
+      // Wiki not ready or config tiddler unreadable → keep empty overrides.
+      this.overrides = {}
+    }
+  }
+
+  /** Merge a patch into the overrides and persist the tiddler. */
+  async set(client: TiddlyWebClient, patch: PluginConfigShape): Promise<PluginConfigShape> {
+    this.overrides = deepMerge(this.overrides, patch) as PluginConfigShape
+    await client.put({
+      title: CONFIG_TIDDLER,
+      text: JSON.stringify(this.overrides, null, 2),
+      type: 'application/json',
+      tags: [],
+    })
+    return this.get()
+  }
+}

package/src/host/git.ts

@@ -0,0 +1,218 @@
+/**
+ * Git face (design doc §7, D11) — the ONLY place dsh-tiddlywiki shells out to
+ * git. The wiki folder itself is the repository; the folder is pure text
+ * (FileSystemAdaptor writes one file per tiddler), so git is a natural sync /
+ * backup channel.
+ *
+ * Sync model is the single-thread alternating one:
+ *   1. start of work:  `git pull --rebase --autostash`
+ *   2. end of work:    `git add -A && git commit && git push`
+ *   3. auto-commit:    debounced 60s commit after wiki writes (AutoCommitter)
+ *
+ * Conflict policy (user-confirmed, no complex handling): a rebase conflict
+ * (only reachable by "forgot to pull before writing") → `git rebase --abort`
+ * + report the unmerged files. Never auto-merge data.
+ *
+ * @module dsh-tiddlywiki/host/git
+ */
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileP = promisify(execFile)
+
+/** Timeout for quick read-only queries. */
+const QUICK_TIMEOUT_MS = 5_000
+
+/** Timeout for structural/network operations. */
+const HEAVY_TIMEOUT_MS = 60_000
+
+export interface ExecResult { ok: boolean; stdout: string; stderr: string }
+export type ExecFn = (args: string[], options: { cwd?: string; timeout?: number }) => Promise<ExecResult>
+
+/** Default exec layer: run `git <args>` under a cwd with a timeout. */
+const defaultExec: ExecFn = async (args, options) => {
+  try {
+    const { stdout, stderr } = await execFileP('git', args, {
+      cwd: options.cwd,
+      timeout: options.timeout ?? QUICK_TIMEOUT_MS,
+      windowsHide: true,
+      encoding: 'utf8',
+      maxBuffer: 32 * 1024 * 1024,
+    })
+    return { ok: true, stdout, stderr }
+  } catch (err) {
+    const e = err as { stdout?: string; stderr?: string; message?: string }
+    return { ok: false, stdout: e.stdout ?? '', stderr: e.stderr ?? String(e.message ?? err) }
+  }
+}
+
+export interface GitStatusView {
+  exists: boolean
+  branch: string
+  dirty: boolean
+  dirtyFiles: string[]
+  remote: string
+  lastCommit?: string
+  ahead?: number
+  behind?: number
+}
+
+export interface GitActionResult { ok: boolean; message: string; conflictFiles?: string[] }
+
+function parseCount(line: string, re: RegExp): number | undefined {
+  const m = line.match(re)
+  return m === null ? undefined : Number(m[1])
+}
+
+export class GitFace {
+  constructor(private readonly exec: ExecFn = defaultExec) {}
+
+  async isRepo(dir: string): Promise<boolean> {
+    const r = await this.exec(['rev-parse', '--is-inside-work-tree'], { cwd: dir, timeout: 2_000 })
+    return r.ok && r.stdout.trim() === 'true'
+  }
+
+  async init(dir: string, branch = 'main'): Promise<boolean> {
+    const r = await this.exec(['init', '-b', branch], { cwd: dir, timeout: HEAVY_TIMEOUT_MS })
+    return r.ok
+  }
+
+  /** Initial commit for a fresh repo (tolerates an empty index). */
+  async initialCommit(dir: string): Promise<boolean> {
+    await this.exec(['add', '-A'], { cwd: dir, timeout: HEAVY_TIMEOUT_MS })
+    const r = await this.exec([...identity(), 'commit', '-m', 'chore(dsh-tiddlywiki): initial commit'], { cwd: dir, timeout: HEAVY_TIMEOUT_MS })
+    return r.ok || /nothing to commit/.test(r.stderr + r.stdout)
+  }
+
+  /**
+   * Stage everything and commit; a local identity is always provided so the
+   * plugin never depends on the machine's global git config. Returns whether
+   * a commit actually happened.
+   */
+  async commit(dir: string, message: string): Promise<{ committed: boolean; message: string }> {
+    await this.exec(['add', '-A'], { cwd: dir, timeout: HEAVY_TIMEOUT_MS })
+    const staged = await this.exec(['diff', '--cached', '--quiet'], { cwd: dir, timeout: QUICK_TIMEOUT_MS })
+    // `diff --cached --quiet` exits 0 when nothing is staged → nothing to commit.
+    if (staged.ok) return { committed: false, message: 'nothing to commit' }
+    const r = await this.exec([...identity(), 'commit', '-m', message], { cwd: dir, timeout: HEAVY_TIMEOUT_MS })
+    return r.ok
+      ? { committed: true, message }
+      : { committed: false, message: `commit failed: ${(r.stderr.trim() || r.stdout.trim()).slice(0, 500)}` }
+  }
+
+  async status(dir: string): Promise<GitStatusView> {
+    const empty: GitStatusView = { exists: false, branch: '', dirty: false, dirtyFiles: [], remote: '' }
+    const r = await this.exec(['status', '--porcelain', '-b'], { cwd: dir, timeout: QUICK_TIMEOUT_MS })
+    if (!r.ok) return empty
+    const lines = r.stdout.split('\n').filter((l) => l.length > 0)
+    const branchLine = lines.find((l) => l.startsWith('## '))
+    const branch = branchLine === undefined ? '' : branchLine.slice(3).split('...')[0] ?? ''
+    const ahead = branchLine === undefined ? undefined : parseCount(branchLine, /ahead (\d+)/)
+    const behind = branchLine === undefined ? undefined : parseCount(branchLine, /behind (\d+)/)
+    const dirty = lines.some((l) => !l.startsWith('## '))
+    const dirtyFiles = lines.filter((l) => !l.startsWith('## ')).map((l) => l.slice(3).trim()).filter(Boolean)
+    const remoteR = await this.exec(['remote', '-v'], { cwd: dir, timeout: QUICK_TIMEOUT_MS })
+    const remote = remoteR.ok ? remoteR.stdout.split('\n').map((l) => l.trim()).find(Boolean) ?? '' : ''
+    const lastR = await this.exec(['log', '-1', '--format=%h %s'], { cwd: dir, timeout: QUICK_TIMEOUT_MS })
+    const lastCommit = lastR.ok && lastR.stdout.trim().length > 0 ? lastR.stdout.trim() : undefined
+    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> {
+    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' }
+    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)
+    return { ok: false, message: conflictFiles.length > 0 ? `conflict in ${conflictFiles.join(', ')} (rebase aborted): ${reason}` : `pull failed: ${reason}`, ...(conflictFiles.length > 0 ? { conflictFiles } : {}) }
+  }
+
+  async push(dir: string): Promise<GitActionResult> {
+    const r = await this.exec(['push'], { cwd: dir, timeout: HEAVY_TIMEOUT_MS })
+    return r.ok
+      ? { ok: true, message: r.stdout.trim() || 'push ok' }
+      : { ok: false, message: (r.stderr.trim() || r.stdout.trim()).slice(0, 500) }
+  }
+
+  /** First push with upstream tracking (called once after a remote is set). */
+  async firstPush(dir: string): Promise<GitActionResult> {
+    const branch = (await this.status(dir)).branch || 'main'
+    const r = await this.exec(['push', '-u', 'origin', branch], { cwd: dir, timeout: HEAVY_TIMEOUT_MS })
+    return r.ok
+      ? { ok: true, message: `pushed ${branch} to origin` }
+      : { ok: false, message: (r.stderr.trim() || r.stdout.trim()).slice(0, 500) }
+  }
+
+  /** Ensure `origin` points at `url` (add or set-url). */
+  async ensureRemote(dir: string, url: string): Promise<GitActionResult> {
+    const cur = await this.exec(['remote', 'get-url', 'origin'], { cwd: dir, timeout: QUICK_TIMEOUT_MS })
+    if (cur.ok) {
+      if (cur.stdout.trim() === url) return { ok: true, message: 'remote origin already set' }
+      const set = await this.exec(['remote', 'set-url', 'origin', url], { cwd: dir, timeout: HEAVY_TIMEOUT_MS })
+      return set.ok ? { ok: true, message: `remote origin → ${url}` } : { ok: false, message: set.stderr.trim() || 'remote set-url failed' }
+    }
+    const add = await this.exec(['remote', 'add', 'origin', url], { cwd: dir, timeout: HEAVY_TIMEOUT_MS })
+    return add.ok ? { ok: true, message: `remote origin → ${url}` } : { ok: false, message: add.stderr.trim() || 'remote add failed' }
+  }
+
+  private async unmergedFiles(dir: string): Promise<string[]> {
+    const r = await this.exec(['diff', '--name-only', '--diff-filter=U'], { cwd: dir, timeout: QUICK_TIMEOUT_MS })
+    return r.ok ? r.stdout.split('\n').map((l) => l.trim()).filter(Boolean) : []
+  }
+}
+
+/** Always-on local identity so commits never depend on global git config. */
+function identity(): string[] {
+  return ['-c', 'user.name=dsh-tiddlywiki', '-c', 'user.email=dsh-tiddlywiki@local']
+}
+
+export interface AutoCommitterOptions {
+  git: GitFace
+  dir: string
+  enabled: boolean
+  debounceMs: number
+  message: () => string
+  onError?: (err: unknown) => void
+  onCommit?: (info: { committed: boolean; message: string }) => void
+}
+
+/**
+ * Debounced auto-committer: every wiki write calls `touch()`; the commit
+ * fires once writes settle for `debounceMs`. Disable with git.autoCommit.
+ */
+export class AutoCommitter {
+  private timer: NodeJS.Timeout | undefined
+  private disposed = false
+
+  constructor(private readonly options: AutoCommitterOptions) {}
+
+  touch(): void {
+    if (!this.options.enabled || this.disposed) return
+    if (this.timer !== undefined) clearTimeout(this.timer)
+    this.timer = setTimeout(() => { void this.flush() }, this.options.debounceMs)
+  }
+
+  /** Run a commit now (also cancels the pending debounce). */
+  async flush(): Promise<void> {
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer)
+      this.timer = undefined
+    }
+    if (!this.options.enabled || this.disposed) return
+    try {
+      const result = await this.options.git.commit(this.options.dir, this.options.message())
+      this.options.onCommit?.(result)
+    } catch (err) {
+      this.options.onError?.(err)
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer)
+      this.timer = undefined
+    }
+  }
+}

package/src/host/routes.ts

@@ -0,0 +1,233 @@
+/**
+ * DSH webserver routes for dsh-tiddlywiki (design doc §10).
+ *
+ * | route                     | method | purpose                                  |
+ * |---------------------------|--------|------------------------------------------|
+ * | /dsh-tiddlywiki/status    | GET    | panel health (service / url / git / tag) |
+ * | /dsh-tiddlywiki/note      | POST   | quick-note → independent tiddler         |
+ * | /dsh-tiddlywiki/restart   | POST   | one-click retry/restart of the TW child  |
+ * | /dsh-tiddlywiki/api/*     | any    | passthrough to the TW service (JSON)     |
+ *
+ * Matching is exact-over-prefix, so the exact routes win and the `/api`
+ * prefix catches the rest. Client calls are same-origin (the DSH web server),
+ * so no CORS is involved.
+ *
+ * @module dsh-tiddlywiki/host/routes
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { TiddlyWebClient } from './tw-api.ts'
+import type { WikiServer } from './wiki.ts'
+import type { GitFace } from './git.ts'
+import { PATH_PREFIX } from './wiki.ts'
+
+export const ROUTE_PREFIX = PATH_PREFIX
+
+/** Max JSON body for note/restart. */
+const MAX_BODY_BYTES = 2 * 1024 * 1024
+
+/** Max passthrough body (tiddler content can be large). */
+const MAX_PROXY_BODY_BYTES = 16 * 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
+}
+
+export interface RouteDeps {
+  server: WikiServer
+  getClient: () => TiddlyWebClient | undefined
+  git: GitFace
+  autoCommit: () => void
+  noteDefaults: () => { tag: string }
+  getWikiPath: () => string
+}
+
+function readBody(req: IncomingMessage, limit = MAX_BODY_BYTES): Promise<string> {
+  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('body too large'))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => resolveP(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', rejectP)
+  })
+}
+
+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' })
+  res.end(body)
+}
+
+function pad(n: number): string {
+  return n < 10 ? `0${n}` : String(n)
+}
+
+/** Default note title: `YYYY-MM-DD HH:mm` (design doc D6). */
+function timestampTitle(date = new Date()): string {
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`
+}
+
+/**
+ * Open a tiddler in TW's NATIVE editor: save the tiddler (when text is
+ * non-empty), reuse or create a DRAFT tiddler carrying `draft.of`/`draft.title`
+ * (TW's story view renders drafts with the EditTemplate — list.js:
+ * `isDraft && editTemplate`), and return the draft title so the client can
+ * navigate the panel iframe to `#<draftTitle>`.
+ */
+export async function openInTwEditor(
+  client: TiddlyWebClient,
+  title: string,
+  text: string,
+  tag: string,
+): Promise<{ title: string; draftTitle: string }> {
+  if (text.trim().length > 0) {
+    await client.put({ title, text, tags: [tag] })
+  }
+  // Draft content: the provided text, else the existing tiddler's content.
+  let draftText = text
+  if (draftText.trim().length === 0) {
+    const existing = await client.get(title)
+    draftText = existing?.text ?? ''
+  }
+  // Reuse an existing draft for this title (mirrors wiki.findDraft).
+  let draftTitle: string | undefined
+  try {
+    const items = await client.list(undefined, true)
+    for (const item of items) {
+      if (item['draft.of'] === title && typeof item.title === 'string') {
+        draftTitle = item.title
+        break
+      }
+    }
+  } catch {
+    /* fall back to a fresh draft */
+  }
+  if (draftTitle === undefined) draftTitle = `Draft of "${title}" ${Date.now()}`
+  await client.put({ title: draftTitle, text: draftText, 'draft.of': title, 'draft.title': title, type: 'text/vnd.tiddlywiki' })
+  return { title, draftTitle }
+}
+
+export function registerRoutes(ctx: { webServer: WebServerFace }, deps: RouteDeps): () => void {
+  const handleStatus = async (_req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    const view = deps.server.status()
+    let gitSummary: GitStatusViewPublic | null = null
+    try {
+      gitSummary = await deps.git.status(deps.getWikiPath())
+    } catch {
+      gitSummary = null
+    }
+    json(res, { ok: true, ...view, git: gitSummary, note: { tag: deps.noteDefaults().tag } })
+  }
+
+  const handleNote = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    try {
+      const body = JSON.parse(await readBody(req)) as { title?: unknown; tag?: unknown; text?: unknown }
+      const text = typeof body.text === 'string' && body.text.trim().length > 0 ? body.text.trim() : null
+      if (text === null) {
+        json(res, { ok: false, error: 'text is required' }, 400)
+        return
+      }
+      const client = deps.getClient()
+      if (client === undefined) {
+        json(res, { ok: false, error: 'wiki service is not running' }, 503)
+        return
+      }
+      const title = typeof body.title === 'string' && body.title.trim().length > 0 ? body.title.trim() : timestampTitle()
+      const tag = typeof body.tag === 'string' && body.tag.trim().length > 0 ? body.tag.trim() : deps.noteDefaults().tag
+      await client.put({ title, text, tags: [tag] })
+      deps.autoCommit()
+      json(res, { ok: true, title, tag, text })
+    } catch (err) {
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+    }
+  }
+
+  const handleEdit = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    try {
+      const body = JSON.parse(await readBody(req)) as { title?: unknown; tag?: unknown; text?: unknown }
+      const client = deps.getClient()
+      if (client === undefined) {
+        json(res, { ok: false, error: 'wiki service is not running' }, 503)
+        return
+      }
+      const title = typeof body.title === 'string' && body.title.trim().length > 0 ? body.title.trim() : timestampTitle()
+      const tag = typeof body.tag === 'string' && body.tag.trim().length > 0 ? body.tag.trim() : deps.noteDefaults().tag
+      const text = typeof body.text === 'string' ? body.text : ''
+      const result = await openInTwEditor(client, title, text, tag)
+      deps.autoCommit()
+      json(res, { ok: true, ...result, twUrl: deps.server.url })
+    } catch (err) {
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+    }
+  }
+
+  const handleRestart = async (_req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    try {
+      await deps.server.restart()
+      json(res, { ok: true, status: deps.server.status().status })
+    } catch (err) {
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
+    }
+  }
+
+  /** Passthrough /dsh-tiddlywiki/api/<rest> → TW root /<rest>. */
+  const handleApiProxy = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    const client = deps.getClient()
+    if (client === undefined) {
+      json(res, { ok: false, error: 'wiki service is not running' }, 503)
+      return
+    }
+    const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+    const rest = url.pathname.replace(/^\/dsh-tiddlywiki\/api/, '') || '/'
+    try {
+      const headers: Record<string, string> = {}
+      const ct = req.headers['content-type']
+      if (typeof ct === 'string') headers['content-type'] = ct
+      const method = (req.method ?? 'GET').toUpperCase()
+      // TW's CSRF gate requires X-Requested-With on writes; forward it through.
+      if (method === 'PUT' || method === 'DELETE' || method === 'POST') headers['x-requested-with'] = 'TiddlyWiki'
+      const init: RequestInit = { method, headers, signal: AbortSignal.timeout(15_000) }
+      if (method === 'PUT' || method === 'POST') init.body = await readBody(req, MAX_PROXY_BODY_BYTES)
+      const upstream = await fetch(`${deps.server.url}${rest}${url.search}`, init)
+      const data = await upstream.text()
+      res.writeHead(upstream.status, {
+        'content-type': upstream.headers.get('content-type') ?? 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+      })
+      res.end(data)
+    } catch (err) {
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 502)
+    }
+  }
+
+  const disposers = [
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/status`, handler: (req, res) => { void handleStatus(req, res) } }),
+    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}/restart`, handler: (req, res) => { void handleRestart(req, res) } }),
+    ctx.webServer.register({ kind: 'prefix', path: `${ROUTE_PREFIX}/api`, handler: (req, res) => { void handleApiProxy(req, res) } }),
+  ]
+  return () => {
+    for (const dispose of disposers) dispose()
+  }
+}
+
+/** Public shape of the git status summary sent to the panel. */
+export interface GitStatusViewPublic {
+  exists: boolean
+  branch: string
+  dirty: boolean
+  dirtyFiles: string[]
+  remote: string
+  lastCommit?: string
+  ahead?: number
+  behind?: number
+}

package/src/host/seed-notes.ts

@@ -0,0 +1,62 @@
+/**
+ * Built-in doc note for the plugin (design doc §14): a short user-facing
+ * "how to use dsh-tiddlywiki" note that is seeded into the wiki on first run.
+ *
+ * Idempotent seed (create-if-missing): on every plugin start we check whether
+ * the note tiddler exists and only write it when it is absent — deleting it
+ * and restarting dsh web recreates it, but editing it never gets overwritten.
+ *
+ * @module dsh-tiddlywiki/host/seed-notes
+ */
+import type { TiddlyWebClient } from './tw-api.ts'
+
+/** Note tiddler title (a normal, searchable note — not a system tiddler). */
+export const DOC_NOTE_TITLE = 'dsh-tiddlywiki 插件说明'
+
+/** Tag that makes the note easy to find via `tiddlywiki_search tag=docs`. */
+export const DOC_NOTE_TAG = 'docs'
+
+/** The note body, TiddlyWiki wiki-text. */
+export const DOC_NOTE_TEXT = `! dsh-tiddlywiki 插件说明
+
+本插件把 **TiddlyWiki 5** 作为 DSH 的持久知识库（wiki 文件夹本身就是一个 git 仓库，随内容自动提交/同步）。
+
+!! 它能做什么
+
+* **5 个 agent 工具**：\`tiddlywiki_search\`（检索）/ \`tiddlywiki_get\`（读）/ \`tiddlywiki_put\`（写）/ \`tiddlywiki_delete\`（删）/ \`tiddlywiki_git_sync\`（git 同步）。
+* **TW 编辑器面板**：侧边栏「TiddlyWiki」按钮 → 在界面中央打开完整版 TW 编辑器。
+* **快速笔记**：右下角悬浮「📝 快速笔记」写随手记，\`Ctrl+Enter\` 保存；点「✏️ 在 TW 中编辑」会弹出独立小窗用 TW 原生编辑器编辑。
+* **git 同步**：写入自动防抖 commit（默认 60 秒）；手动 \`tiddlywiki_git_sync action=sync\` 做 pull → commit → push。
+* **设置页**：DSH 设置 → 「TiddlyWiki 知识库」管理插件/主题/语言与运行配置。
+
+!! 知识库纪律（三条）
+
+1. 开工先 \`tiddlywiki_git_sync action=pull\`（rebase + autostash，真冲突会自动 abort 并报文件）。
+2. 收工 \`tiddlywiki_git_sync action=sync\`。
+3. 插件自动 commit 兜底，手动 sync 用于需要主动推送的场合。
+
+!! 主题与语言
+
+* **主题**分两层：每行一个「☑ 加载」（多选 = TW 里可用的主题，依赖链自动带上）和「◉ 活动」（单选 = 当前视觉主题）。应用后自动重启 TW。
+* **语言**：设置页勾选 \`zh-Hans\`（简体）并应用，TW 界面即切换为中文。
+
+!! 说明
+
+* 本笔记由插件在首次启动时自动写入 wiki（幂等：不存在才写）。删除后重启 dsh web 会重建；手动编辑过的内容不会被覆盖。
+* 更多细节见插件仓库 README。`
+
+/**
+ * Seed the doc note when it is absent. Returns whether a note was written.
+ * Never throws (missing wiki or note already present → no-op / false).
+ */
+export async function seedDocNote(client: TiddlyWebClient): Promise<boolean> {
+  const existing = await client.get(DOC_NOTE_TITLE).catch(() => undefined)
+  if (existing !== undefined) return false
+  await client.put({
+    title: DOC_NOTE_TITLE,
+    text: DOC_NOTE_TEXT,
+    type: 'text/vnd.tiddlywiki',
+    tags: [DOC_NOTE_TAG],
+  })
+  return true
+}