@xp266/dshtui 0.1.0

package/src/index.tsx

@@ -0,0 +1,185 @@
+import './runtime/prod-react.ts'
+import { setColorLevel } from './terminal/capabilities.ts'
+import { probeColorLevel } from './terminal/probe.ts'
+import { render } from 'ink'
+import { startPerformanceGuard } from './performance-guard.ts'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { App } from './ui/app.tsx'
+import { createChatBridge } from './chat/bridge.ts'
+import type { ChatBridge } from './chat/bridge.ts'
+import { createScreenCapture } from './terminal/screen.ts'
+import { writeCursorShape } from './terminal/cursor-shape.ts'
+import { startHotTheme } from './hot-theme.ts'
+import { applyTheme } from './apply-theme.ts'
+import { registerPalette } from './theme.ts'
+import { detectBackgroundMode } from './terminal/background.ts'
+import { registerThemeSettings } from './theme-settings.ts'
+import type { ThemeSettingsScope } from './theme-settings.ts'
+import { warmLanguages, onLanguagesWarm, clearHighlightCache } from './ui/message/md/highlight.ts'
+import { clearMarkdownBlockCache } from './ui/message/md/engine.ts'
+import { clearLayoutCache } from './ui/message/layout.ts'
+import { warmRenderPipeline } from './ui/message/warmup.ts'
+import { createTuiExtensionPoint, exposeRuntimeFaces } from './ui/extension-point.ts'
+import { registerBuiltinToolViews } from './chat/builtin-tool-views.ts'
+import { closeBootLog, emitBootLine, openBootLog } from './boot-log.ts'
+import { configureLogs, error as logError, installCrashHandlers, warn } from './log.ts'
+import { env } from './env.ts'
+import { upstreamDriftSummary, UPSTREAM_SUPPORTED_RANGE } from './contract/upstream.ts'
+
+export const name = '@xp266/dshtui'
+
+export interface Config {
+  theme: 'auto' | 'dark' | 'light'
+  /** Palette overrides applied on top of the built-in dark and light themes (palette key -> hex). */
+  colors: Record<string, string>
+  maxFps: number
+  bootListTimeout: number
+  alternateScreen: boolean
+}
+
+export const Config: z<Config> = z.object({
+  theme: z.union(['auto', 'dark', 'light']).default('auto'),
+  colors: z.dict(z.string()).default({}),
+  maxFps: z.number().default(240),
+  bootListTimeout: z.number().default(10000),
+  alternateScreen: z.boolean().default(true),
+})
+
+const DEFAULT_CONFIG: Config = { theme: 'auto', colors: {}, maxFps: 240, bootListTimeout: 10000, alternateScreen: true }
+
+async function initTheme(scope: ThemeSettingsScope | undefined, theme: Config['theme'], colors: Config['colors']): Promise<void> {
+  if (Object.keys(colors).length > 0) {
+    registerPalette({ id: 'dshtui-config', order: Number.MAX_SAFE_INTEGER, colors })
+  }
+  const saved = scope?.get().mode
+  applyTheme(saved === 'dark' || saved === 'light'
+    ? saved
+    : theme === 'auto'
+      ? await detectBackgroundMode()
+      : theme)
+}
+
+export const inject = ['agentLoop', 'agents', 'sessions', 'workspaceRegistry', 'llm', 'settings', 'credentials', 'agentDefaultModel']
+
+export function apply(ctx: Context, config: Config = Config(DEFAULT_CONFIG)) {
+  ctx.effect(() => {
+    configureLogs({ stderr: env.debug, file: env.logFile, dir: env.logDir, level: env.logLevel, maxFileBytes: env.logMaxBytes })
+    const restorePerformance = startPerformanceGuard()
+    const disposeCrashHandlers = installCrashHandlers({ exit: env.crashExit })
+    const drift = upstreamDriftSummary()
+    if (drift !== undefined) {
+      warn('upstream', `upstream version drift (supported: ${UPSTREAM_SUPPORTED_RANGE}): ${drift.kind} ${drift.versions.join(', ')}`)
+    }
+    const capture = createScreenCapture()
+    let bridge: ChatBridge | undefined
+    let app: ReturnType<typeof render> | undefined
+    let hotTheme: ReturnType<typeof startHotTheme> | undefined
+    let themeTick = 0
+    let disposed = false
+    let lastColumns = 0
+    let lastRows = 0
+    let stopSizePoll: (() => void) | undefined
+    let exposeFaces: (() => void) | undefined
+    const buildAppNode = () => <App bridge={bridge} screen={capture} themeTick={themeTick} />
+    const rerender = (): void => {
+      themeTick += 1
+      app?.rerender(buildAppNode())
+    }
+    // NOTE: the extension object must come from createTuiExtensionPoint itself;
+    // ctx.get('tui') here would run before provide() and stay undefined forever.
+    const { extension: extensionPoint, dispose: disposeExtensionPoint } = createTuiExtensionPoint(ctx, { onContributionsChanged: rerender })
+    const disposeBuiltinToolViews = registerBuiltinToolViews()
+    warmLanguages()
+    onLanguagesWarm(() => {
+      clearHighlightCache()
+      clearMarkdownBlockCache()
+      clearLayoutCache()
+      warmRenderPipeline()
+    })
+    const start = (): void => {
+      if (disposed || app !== undefined) return
+      app = render(buildAppNode(), {
+        stdout: capture.stream,
+        alternateScreen: config.alternateScreen,
+        exitOnCtrlC: false,
+        incrementalRendering: false,
+        maxFps: config.maxFps,
+        kittyKeyboard: { mode: 'auto' },
+      })
+      lastColumns = capture.stream.columns
+      lastRows = capture.stream.rows
+      const onResize = () => {
+        lastColumns = capture.stream.columns
+        lastRows = capture.stream.rows
+        capture.stream.write('\x1b[2J\x1b[H')
+        app!.clear()
+        app!.rerender(buildAppNode())
+      }
+      capture.stream.on('resize', onResize)
+      const sizePoll = setInterval(() => {
+        if (capture.stream.columns !== lastColumns || capture.stream.rows !== lastRows) {
+          onResize()
+          // Terminals that never emit a resize event still get React-side
+          // size updates through this synthetic dispatch.
+          capture.stream.emit('resize')
+        }
+      }, 1000)
+      sizePoll.unref()
+      stopSizePoll = (): void => {
+        clearInterval(sizePoll)
+        capture.stream.off('resize', onResize)
+      }
+      if (disposed) {
+        stopSizePoll()
+        return
+      }
+      hotTheme = startHotTheme(rerender)
+    }
+    const themeScope = registerThemeSettings(ctx)
+    openBootLog()
+    if (drift !== undefined) {
+      emitBootLine(`warning: upstream version drift (${drift.kind})`)
+    }
+    emitBootLine('terminal: probing color support')
+    void (async () => {
+      const probed = await probeColorLevel()
+      if (probed !== undefined) setColorLevel(probed)
+      emitBootLine('theme: applying initial theme')
+      await initTheme(themeScope, config.theme, config.colors)
+      emitBootLine('chat bridge: connecting harness services')
+      bridge = await createChatBridge(ctx)
+      exposeFaces = exposeRuntimeFaces(extensionPoint, bridge)
+      emitBootLine('sessions: loading session list')
+      await Promise.race([
+        bridge.listSessions().catch(() => {}),
+        new Promise<void>(resolve => {
+          setTimeout(resolve, config.bootListTimeout).unref()
+        }),
+      ])
+      emitBootLine('ready: starting interface')
+      closeBootLog()
+    })()
+      .catch(error => {
+        logError('boot', 'chat bridge init failed', {
+          message: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined,
+        })
+        closeBootLog()
+      })
+      .finally(() => start())
+    return () => {
+      disposed = true
+      restorePerformance()
+      exposeFaces?.()
+      disposeBuiltinToolViews()
+      disposeExtensionPoint()
+      stopSizePoll?.()
+      hotTheme?.stop()
+      writeCursorShape('reset')
+      bridge?.dispose()
+      app?.unmount()
+      disposeCrashHandlers()
+    }
+  })
+}

package/src/kernel/registry.ts

@@ -0,0 +1,102 @@
+type Listener = () => void
+
+export interface KeyedOptions {
+  order?: number
+}
+
+interface Layer<T> {
+  key: string
+  order: number
+  value: T
+  prev: Layer<T> | undefined
+  dead: boolean
+}
+
+export interface KeyedEntry<T> {
+  key: string
+  order: number
+  value: T
+}
+
+export interface KeyedRegistry<T> {
+  register(key: string, value: T, options?: KeyedOptions): () => void
+  entries(): KeyedEntry<T>[]
+  values(): T[]
+  get(key: string): T | undefined
+  has(key: string): boolean
+  subscribe(listener: Listener): () => void
+}
+
+/**
+ * Keyed contribution registry with layered override semantics: registering
+ * an existing key displaces the previous layer, and disposing a layer
+ * restores the nearest live layer below it, so an overriding plugin that
+ * unmounts hands the slot back to whatever it replaced.
+ *
+ * `get(key)` resolves to the live layer with the lowest order (the one that
+ * would win a dispatch loop), not merely the most recently registered one, so
+ * single-key lookups agree with the iteration order plugins observe.
+ */
+export function keyedRegistry<T>(compareKeys: (a: string, b: string) => number = (a, b) => (a < b ? -1 : a > b ? 1 : 0)): KeyedRegistry<T> {
+  const map = new Map<string, Layer<T>>()
+  const listeners = new Set<Listener>()
+
+  function notify(): void {
+    for (const listener of [...listeners]) {
+      try {
+        listener()
+      } catch {
+        // One broken listener must not starve the others or corrupt registry state.
+      }
+    }
+  }
+
+  function winningLayer(key: string): Layer<T> | undefined {
+    let best: Layer<T> | undefined
+    let layer = map.get(key)
+    while (layer !== undefined) {
+      if (!layer.dead && (best === undefined || layer.order < best.order)) best = layer
+      layer = layer.prev
+    }
+    return best
+  }
+
+  return {
+    register(key, value, options) {
+      const prev = map.get(key)
+      const layer: Layer<T> = { key, order: options?.order ?? 100, value, prev, dead: false }
+      map.set(key, layer)
+      notify()
+      return () => {
+        if (layer.dead) return
+        layer.dead = true
+        if (map.get(key) !== layer) return
+        let restore = layer.prev
+        while (restore !== undefined && restore.dead) restore = restore.prev
+        if (restore === undefined) map.delete(key)
+        else map.set(key, restore)
+        notify()
+      }
+    },
+    entries() {
+      return [...map.values()]
+        .map(layer => ({ key: layer.key, order: layer.order, value: layer.value }))
+        .sort((a, b) => a.order - b.order || compareKeys(a.key, b.key))
+    },
+    values() {
+      return this.entries().map(entry => entry.value)
+    },
+    get(key) {
+      return winningLayer(key)?.value
+    },
+    has(key) {
+      return map.has(key)
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+  }
+}

package/src/kernel/surface.ts

@@ -0,0 +1,33 @@
+import { clearHighlightCache } from '../ui/message/md/highlight.ts'
+import { clearMarkdownBlockCache } from '../ui/message/md/engine.ts'
+import { clearLayoutCache } from '../ui/message/layout.ts'
+
+type Listener = () => void
+
+const listeners = new Set<Listener>()
+
+/**
+ * Single invalidation point for every rendered-surface cache (message layout,
+ * markdown blocks, syntax highlight) plus the rerender notification. Theme
+ * switches, hot reloads, and contribution changes all funnel through here so
+ * no cache can be missed when the surface changes.
+ */
+export function bumpSurface(): void {
+  clearLayoutCache()
+  clearHighlightCache()
+  clearMarkdownBlockCache()
+  for (const listener of [...listeners]) {
+    try {
+      listener()
+    } catch {
+      // isolated: one broken subscriber must not block the others
+    }
+  }
+}
+
+export function onSurfaceChanged(listener: Listener): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}

package/src/log.ts

@@ -0,0 +1,249 @@
+import { appendFileSync, chmodSync, mkdirSync, renameSync, statSync, unlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { resolveDshHome } from './harness-home.ts'
+
+const LOG_LEVELS = ['debug', 'info', 'warn', 'error'] as const
+export type LogLevel = (typeof LOG_LEVELS)[number]
+
+export interface LogLine {
+  level: LogLevel
+  tag: string
+  message: string
+  fields?: Record<string, unknown>
+}
+
+export interface CrashReport {
+  kind: 'uncaughtException' | 'unhandledRejection' | 'boot'
+  message: string
+  stack?: string
+  cause?: string
+  fields?: Record<string, unknown>
+}
+
+export interface LogSink {
+  line(entry: LogLine): void
+  crash(report: CrashReport): void
+}
+
+export interface LogConfig {
+  dir?: string
+  stderr?: boolean
+  file?: boolean
+  level?: LogLevel
+  maxFileBytes?: number
+}
+
+const DEFAULT_MAX_FILE_BYTES = 5 * 1024 * 1024
+
+const state = {
+  stderrEnabled: false,
+  fileEnabled: false,
+  minLevel: 'info' as LogLevel,
+  maxFileBytes: DEFAULT_MAX_FILE_BYTES,
+}
+
+const sinks = new Set<LogSink>()
+let fileSink: LogSink | undefined
+
+function levelRank(level: LogLevel): number {
+  return LOG_LEVELS.indexOf(level)
+}
+
+function fieldsText(fields: Record<string, unknown> | undefined): string {
+  return fields === undefined ? '' : ` ${JSON.stringify(fields)}`
+}
+
+function formatLine(entry: LogLine): string {
+  return `${new Date().toISOString()} [${entry.level}] ${entry.tag} ${entry.message}${fieldsText(entry.fields)}\n`
+}
+
+function formatCrash(report: CrashReport): string {
+  return [
+    `=== dshtui crash: ${report.kind} ===`,
+    `time: ${new Date().toISOString()}`,
+    `node: ${process.version}`,
+    `message: ${report.message}${fieldsText(report.fields)}`,
+    report.stack === undefined ? '' : `stack:\n${report.stack}`,
+    report.cause === undefined ? '' : `cause: ${report.cause}`,
+    '',
+  ].join('\n')
+}
+
+function writeStderr(line: string): void {
+  if (!state.stderrEnabled) return
+  try {
+    process.stderr.write(line)
+  } catch {
+    // Diagnostics must never take the UI down.
+  }
+}
+
+function resolveLogFile(dir: string | undefined): string {
+  return join(dir ?? join(resolveDshHome(), 'logs'), 'dshtui.log')
+}
+
+function rotateIfNeeded(logFile: string): void {
+  let size: number
+  try {
+    size = statSync(logFile).size
+  } catch {
+    return
+  }
+  if (size < state.maxFileBytes) return
+  try {
+    unlinkSync(`${logFile}.1`)
+  } catch {
+    // No previous rotation to clear.
+  }
+  try {
+    renameSync(logFile, `${logFile}.1`)
+  } catch {
+    // Keep appending to the oversized file rather than losing diagnostics.
+  }
+}
+
+function fileSinkFor(logFile: string): LogSink {
+  return {
+    line(entry) {
+      if (!state.fileEnabled) return
+      try {
+        rotateIfNeeded(logFile)
+        try {
+          chmodSync(logFile, 0o600)
+        } catch {
+          // The log may not exist yet; the create mode below still guards it.
+        }
+        appendFileSync(logFile, formatLine(entry), { mode: 0o600 })
+      } catch {
+        // Diagnostics must never take the UI down.
+      }
+      if (entry.level === 'warn' || entry.level === 'error') {
+        writeStderr(`[dshtui] ${entry.message}${fieldsText(entry.fields)}\n`)
+      }
+    },
+    crash(report) {
+      if (!state.fileEnabled) return
+      const line = formatCrash(report)
+      try {
+        rotateIfNeeded(logFile)
+        try {
+          chmodSync(logFile, 0o600)
+        } catch {
+          // The log may not exist yet; the create mode below still guards it.
+        }
+        appendFileSync(logFile, line, { mode: 0o600 })
+      } catch {
+        // Diagnostics must never take the UI down.
+      }
+      writeStderr(line)
+    },
+  }
+}
+
+function removeFileSink(): void {
+  if (fileSink === undefined) return
+  sinks.delete(fileSink)
+  fileSink = undefined
+}
+
+export function registerLogSink(sink: LogSink): () => void {
+  sinks.add(sink)
+  return () => {
+    sinks.delete(sink)
+  }
+}
+
+export function configureLogs(options: LogConfig = {}): void {
+  if (options.stderr !== undefined) state.stderrEnabled = options.stderr
+  if (options.level !== undefined) state.minLevel = options.level
+  if (options.maxFileBytes !== undefined) state.maxFileBytes = Math.max(1, options.maxFileBytes)
+  state.fileEnabled = options.file ?? state.fileEnabled
+  removeFileSink()
+  if (state.fileEnabled) {
+    const logFile = resolveLogFile(options.dir)
+    try {
+      mkdirSync(dirname(logFile), { recursive: true, mode: 0o700 })
+      fileSink = fileSinkFor(logFile)
+      sinks.add(fileSink)
+    } catch {
+      state.fileEnabled = false
+    }
+  }
+}
+
+function dispatch(entry: LogLine): void {
+  if (levelRank(entry.level) < levelRank(state.minLevel)) return
+  for (const sink of sinks) {
+    try {
+      sink.line(entry)
+    } catch {
+      // Diagnostics must never take the UI down.
+    }
+  }
+}
+
+function dispatchCrash(report: CrashReport): void {
+  for (const sink of sinks) {
+    try {
+      sink.crash(report)
+    } catch {
+      // Diagnostics must never take the UI down.
+    }
+  }
+}
+
+export function log(level: LogLevel, tag: string, message: string, fields?: Record<string, unknown>): void {
+  dispatch({ level, tag, message, fields })
+}
+
+export function debug(tag: string, message: string, fields?: Record<string, unknown>): void {
+  log('debug', tag, message, fields)
+}
+
+export function info(tag: string, message: string, fields?: Record<string, unknown>): void {
+  log('info', tag, message, fields)
+}
+
+export function warn(tag: string, message: string, fields?: Record<string, unknown>): void {
+  log('warn', tag, message, fields)
+}
+
+export function error(tag: string, message: string, fields?: Record<string, unknown>): void {
+  log('error', tag, message, fields)
+}
+
+function stringifyError(cause: unknown): string {
+  if (cause instanceof Error) return cause.message
+  return String(cause)
+}
+
+export function writeCrashReport(report: CrashReport): void {
+  dispatchCrash(report)
+}
+
+export function installCrashHandlers(options: { exit?: boolean } = {}): () => void {
+  const onUncaught = (cause: unknown): void => {
+    writeCrashReport({
+      kind: 'uncaughtException',
+      message: stringifyError(cause),
+      stack: cause instanceof Error ? cause.stack : undefined,
+    })
+    if (options.exit === true) process.exit(1)
+  }
+  const onRejected = (cause: unknown): void => {
+    writeCrashReport({
+      kind: 'unhandledRejection',
+      message: stringifyError(cause),
+      stack: cause instanceof Error ? cause.stack : undefined,
+    })
+    if (options.exit === true) process.exit(1)
+  }
+  process.on('uncaughtException', onUncaught)
+  process.on('unhandledRejection', onRejected)
+  return () => {
+    process.off('uncaughtException', onUncaught)
+    process.off('unhandledRejection', onRejected)
+  }
+}
+
+export { LOG_LEVELS }

package/src/model/message.ts

@@ -0,0 +1,89 @@
+import type { CustomMessage, ToolReadView } from '../contract/index.ts'
+
+export type { CustomMessage, ToolReadView } from '../contract/index.ts'
+
+export interface BubbleMessage {
+  kind: 'bubble'
+  id: string
+  role: 'user' | 'assistant' | 'error'
+  content: string
+  streaming?: boolean
+  origin?: 'command'
+}
+
+export interface CollapsibleMessage {
+  kind: 'collapsible'
+  id: string
+  label: string
+  body: string
+  running: boolean
+  collapsed: boolean
+  bodyCol?: number
+  thinking?: boolean
+  streaming?: boolean
+  startedAt?: number
+}
+
+export type DiffLineKind = 'ctx' | 'del' | 'add'
+
+export interface DiffLine {
+  kind: DiffLineKind
+  text: string
+}
+
+/**
+ * Generic tool card: every tool shares one bubble shape. The header carries
+ * the tool name plus a parameter summary; the body shows the full arguments
+ * and result (or a diff / read window when the tool protocol produced one).
+ * No per-tool customization exists at this layer.
+ */
+export interface ToolCardMessage {
+  kind: 'tool-card'
+  id: string
+  tool: string
+  /** Header text: tool name plus optional parameter summary. */
+  label: string
+  /** Full call-side arguments, rendered verbatim while running (and after, for full disclosure). */
+  argsBody: string
+  /** Full settled result text from the tool protocol. */
+  resultBody?: string
+  bodyCol?: number
+  diff?: { path: string; hunks: readonly (readonly DiffLine[])[]; backgrounds?: boolean }
+  /** Structured read window replacing the text result body. */
+  read?: ToolReadView
+  /** True when the settled result reported isError without a structured error; the result text renders as the error. */
+  failed?: boolean
+  /** Sub-calls dispatched under this call (code mode); rendered as a child list. */
+  nested?: readonly ToolCardMessage[]
+  error?: string
+  exitCode?: number
+  signal?: string
+  running: boolean
+  streaming?: boolean
+  startedAt?: number
+}
+
+export interface CompactionMessage {
+  kind: 'compaction'
+  id: string
+  compactionId: string
+  running: boolean
+  summary: string
+  error?: string
+  streaming?: boolean
+}
+
+export interface HomeLogoMessage {
+  kind: 'home-logo'
+  id: string
+  /** Artwork lines after culling; empty when the terminal cannot fit the logo. */
+  lines: readonly string[]
+  /** One gradient color per artwork line, aligned with `lines`. */
+  colors: readonly string[]
+  /** Version banner lines rendered under the artwork inside the same bubble. */
+  info: readonly string[]
+}
+
+export type MessageKind = 'bubble' | 'collapsible' | 'tool-card' | 'compaction' | 'custom' | 'home-logo'
+
+export type Message = BubbleMessage | CollapsibleMessage | ToolCardMessage | CompactionMessage | CustomMessage | HomeLogoMessage