dsh-code 0.1.0

package/lib/types/internals.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Injectable process-facing effects for the TUI runner. Tests substitute the
+ * Ink mount with a capturing fake and the streams with string sinks, keeping
+ * the runner's lifecycle testable without a terminal.
+ *
+ * @module @deepseek-ai/dsh-tui/internals
+ */
+import type { ReactElement } from 'react';
+/** A mounted terminal app instance; the runner owns unmount ordering. */
+export interface TuiMount {
+    /** Tear the terminal app down before flush and exit. */
+    unmount(): void;
+}
+/** The Ink mount seam: renders the app element and returns its handle. */
+export type Mount = (element: ReactElement) => TuiMount;
+/** Substitutable runner effects; production values write to the real terminal. */
+export declare const internals: {
+    /** Ink renderer mount; tests substitute a fake that captures the element. */
+    mount: Mount;
+    /** Diagnostics stream for direct-driver failures. */
+    stderr: {
+        write(chunk: string): unknown;
+    };
+};

package/lib/types/invariant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tui`.
+ * @module @deepseek-ai/dsh-tui/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tui-invariant";
+/** Service required before the companion can register. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;

package/lib/types/render/projection.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Pure session-event-to-view projection for the TUI transcript: one reducer
+ * over {@link SessionEvent}s producing the ordered entries the renderer draws.
+ * Rendering never reads the session directly — this module owns the view
+ * model, so tests drive it with plain event arrays.
+ *
+ * @module @deepseek-ai/dsh-tui/render/projection
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** One user prompt line. */
+export interface UserEntry {
+    kind: 'user';
+    /** Joined text blocks of the user message. */
+    text: string;
+}
+/** One assembled assistant reply. */
+export interface AssistantEntry {
+    kind: 'assistant';
+    /** Joined text blocks of the assistant message. */
+    text: string;
+}
+/** One model-requested tool invocation and its settled state. */
+export interface ToolEntry {
+    kind: 'tool';
+    /** Correlation id shared with the matching `tool/result`. */
+    callId: string;
+    /** Tool name as the model addressed it. */
+    name: string;
+    /** Raw arguments JSON string exactly as the model produced it. */
+    arguments: string;
+    /** Execution state; `running` until the paired result lands. */
+    state: 'running' | 'done' | 'error';
+    /** Bounded first text block of the result, empty until it lands. */
+    summary: string;
+}
+/** One turn-level failure surfaced from `turn/end`. */
+export interface ErrorEntry {
+    kind: 'error';
+    /** `code: message` of the failure. */
+    text: string;
+}
+/** Ordered transcript items the renderer draws. */
+export type TranscriptEntry = UserEntry | AssistantEntry | ToolEntry | ErrorEntry;
+/** Cumulative token accounting folded from `assistant/message` usage reports. */
+export interface UsageTotals {
+    /** Prompt-side billed tokens: `inputTokens` plus both cache buckets. */
+    inputTokens: number;
+    /** Completion-side tokens over the whole log. */
+    outputTokens: number;
+    /** Cache-read tokens over the whole log (0 when the adapter reports none). */
+    cacheReadTokens: number;
+}
+/** Window-scoped figures the status line shows; timing uses event timestamps. */
+export interface TranscriptStats {
+    /** Durable turns opened (`turn/start` events). */
+    turns: number;
+    /** Model requests made (`step/start` events). */
+    steps: number;
+    /** Summed model wall time: `step/start` → `assistant/message`, in ms. */
+    llmMs: number;
+    /** Summed tool wall time: `tool/call` → `tool/result`, in ms. */
+    toolMs: number;
+    /** Cumulative token accounting; input stays 0 until a report lands. */
+    usage: UsageTotals;
+}
+/** The complete TUI transcript view for one session. */
+export interface TranscriptView {
+    /** Settled entries in log order. */
+    entries: readonly TranscriptEntry[];
+    /** Text accumulated from `assistant/chunk` deltas since the last flush. */
+    streaming: string;
+    /** Latest whole-list todo snapshot from `todo/write`, empty when none. */
+    todos: SessionEvent<'todo/write'>['data']['todos'];
+    /** True while a durable turn is open (`turn/start` … `turn/end`). */
+    busy: boolean;
+    /** Figures the status line renders. */
+    stats: TranscriptStats;
+    /**
+     * Fold-internal timing anchors, never rendered: open step and tool-call
+     * start timestamps the next `assistant/message` / `tool/result` resolves
+     * against. Keyed `turn:step` and by call id.
+     */
+    readonly anchors: {
+        stepStart: Map<string, number>;
+        toolStart: Map<string, number>;
+    };
+}
+/** A fresh, empty transcript view. */
+export declare function createTranscriptView(): TranscriptView;
+/**
+ * Fold one session event into an updated view (copy-on-write).
+ * @param view - the view before the event.
+ * @param event - one durable session event from `session/event` or the log.
+ * @returns the view after the event; the input view is never mutated.
+ */
+export declare function projectEvent(view: TranscriptView, event: SessionEvent): TranscriptView;
+/**
+ * Fold a replayed event history into one view.
+ * @param events - events in `seq` order.
+ * @returns the folded view.
+ */
+export declare function projectEvents(events: readonly SessionEvent[]): TranscriptView;

package/lib/types/render/status.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Status-line composition for the TUI footer: pipe-separated groups blending
+ * the Claude-Code-style identity facts (model, working directory, git branch,
+ * session) with the web StatsLine's session figures (turns/steps, model and
+ * tool wall time, cache hit, token totals). Pure functions only — the footer
+ * renders exactly what {@link buildStatusGroups} returns.
+ *
+ * @module @deepseek-ai/dsh-tui/render/status
+ */
+import type { TranscriptStats } from './projection.ts';
+/**
+ * Compact token count: 517 / 12.2K / 517K / 1.2M (one decimal under three
+ * digits), mirroring the web composer's StatsLine format.
+ * @param n - token count.
+ * @returns display string.
+ */
+export declare function formatTokens(n: number): string;
+/**
+ * Compact duration: 45.2s under a minute, 2m42s from there on.
+ * @param ms - duration in milliseconds.
+ * @returns display string.
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Cache-hit share of billed prompt-side input.
+ * @param usage - cumulative token totals.
+ * @returns rounded integer percent, or null when no input was billed.
+ */
+export declare function cacheHitPercent(usage: TranscriptStats['usage']): number | null;
+/** Identity facts the runner resolves once at mount; empty strings drop out. */
+export interface StatusFacts {
+    /** `provider/model` selection serving this session. */
+    model: string;
+    /** Working-directory basename the session serves. */
+    cwd: string;
+    /** Git branch name, empty outside a repository or on a detached HEAD file. */
+    branch: string;
+    /** Short session identifier (last dash-separated segment or tail). */
+    sessionId: string;
+}
+/**
+ * Build the footer's display groups; a group with no data drops out whole.
+ * @param facts - identity facts resolved by the runner.
+ * @param stats - session figures folded from the durable log.
+ * @returns one string per pipe-separated group, in display order.
+ */
+export declare function buildStatusGroups(facts: StatusFacts, stats: TranscriptStats): string[];

package/lib/types/store.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Observable transcript store: folds session events into the projection view
+ * and notifies subscribers. The renderer subscribes through
+ * `useSyncExternalStore`; the runner owns event feeding. The store owns no
+ * timing — listeners fire synchronously after each applied event.
+ *
+ * @module @deepseek-ai/dsh-tui/store
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import { type TranscriptView } from './render/projection.ts';
+/** The externally readable, event-fed transcript store for one session. */
+export interface TranscriptStore {
+    /** The current view; the same object identity until an event changes it. */
+    getView(): TranscriptView;
+    /** Subscribe to view changes; returns the unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** Fold one session event; ignored events change nothing and notify nobody. */
+    apply(event: SessionEvent): void;
+}
+/**
+ * Create one transcript store.
+ * @returns the store the runner feeds and the renderer subscribes to.
+ */
+export declare function createTranscriptStore(): TranscriptStore;

package/lib/types/theme.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Terminal color tokens for the dsh TUI, mapped from the product design
+ * platform's DeepSeek palette
+ * (`packages/client/ui-theme/src/styles/design-platform.css`). Truecolor RGB
+ * rides chalk, which degrades automatically on terminals without truecolor.
+ *
+ * @module @deepseek-ai/dsh-tui/theme
+ */
+/**
+ * RGB triples for the TUI, one entry per design-platform token in use.
+ * Keep names and values in sync with the CSS custom properties cited inline.
+ */
+export declare const TUI_RGB: {
+    /** Primary brand blue — `--dsw-static-deepseek-500`. */
+    readonly brand: readonly [65, 118, 230];
+    /** Brighter brand blue for live/streaming emphasis — `--dsw-static-deepseek-400`. */
+    readonly brandBright: readonly [103, 158, 254];
+    /** Deep brand blue for secondary chrome — `--dsw-static-deepseek-600`. */
+    readonly brandDeep: readonly [72, 104, 178];
+    /** Muted caption gray — `--dsw-static-neutral-bluish-600`. */
+    readonly dim: readonly [129, 133, 140];
+    /** Success green — `--dsw-static-green-500`. */
+    readonly success: readonly [34, 197, 94];
+    /** Error red — `--dsw-static-red-500`. */
+    readonly error: readonly [239, 68, 68];
+    /** Warning amber — `--dsw-static-amber-500`. */
+    readonly warn: readonly [245, 158, 11];
+};
+/** Paint with the primary brand blue: whale, wordmark, tool names, accents. */
+export declare function brand(text: string): string;
+/** Paint with the bright brand blue: streaming output and active spinners. */
+export declare function brandBright(text: string): string;
+/** Paint with the deep brand blue: borders and secondary chrome. */
+export declare function brandDeep(text: string): string;
+/** Paint muted captions, hints, and meta lines. */
+export declare function dim(text: string): string;
+/** Paint completed tool results and confirmations. */
+export declare function success(text: string): string;
+/** Paint failures and error entries. */
+export declare function error(text: string): string;
+/** Paint warnings. */
+export declare function warn(text: string): string;

package/lib/types/whale-glyph.d.ts

@@ -0,0 +1,6 @@
+/** Half-block whale glyph rows; render with the brand color. */
+export declare const WHALE_GLYPH: readonly string[];
+/** Fixed glyph width in terminal columns. */
+export declare const WHALE_GLYPH_COLUMNS = 26;
+/** Fixed glyph height in half-block rows. */
+export declare const WHALE_GLYPH_ROWS = 8;

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "dsh-code",
+  "description": "Claude-Code-style interactive TUI bundle for DeepSeek Harness (dsh): DeepSeek-blue whale banner, live session transcript, and a blended status line",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "lib/index.mjs",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.mjs"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.mjs"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "src"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unlinearity/dsh-code.git"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsdown && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "gen:whale": "tsx scripts/gen-whale-glyph.ts"
+  },
+  "engines": {
+    "node": "^22.19 || >=24"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "ink": "^5.2.1",
+    "react": "^18.3.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.0-rc.5",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-default-model": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-cmdline": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-code-runtime-worker-thread": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/react": "~18.3.1",
+    "tsdown": "^0.22.2",
+    "tsx": "^4.22.4",
+    "typescript": "^5.9.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/app.ts

@@ -0,0 +1,201 @@
+/**
+ * The Ink terminal app: whale-and-wordmark header in DeepSeek blue, the live
+ * transcript, the streaming line, local notices, and the input box. All state
+ * arrives through the transcript store (derived from the durable session log)
+ * plus local input state; the app owns no session mutation of its own.
+ *
+ * Element construction uses `createElement` (not JSX): the `dsh` source launch
+ * compiles this file through tsx's ESM-only hook, which does not adopt this
+ * package's `jsx: react-jsx` compiler option, and the classic JSX runtime
+ * would demand a React global.
+ *
+ * @module @deepseek-ai/dsh-tui/app
+ */
+
+import { createElement, useState, useSyncExternalStore, type ReactElement } from 'react'
+import { Box, Text, useInput } from 'ink'
+import { assertNever } from '@deepseek-ai/dsh-llm'
+import { TUI_RGB, brand, dim, error as paintError } from './theme.ts'
+import { WHALE_GLYPH, WHALE_GLYPH_COLUMNS } from './whale-glyph.ts'
+import type { TranscriptStore } from './store.ts'
+import type { TranscriptEntry } from './render/projection.ts'
+import { buildStatusGroups, type StatusFacts } from './render/status.ts'
+
+/** Props the runner hands the app; callbacks stay owned by the runner. */
+export interface AppProps {
+  /** Event-fed transcript store for the live session. */
+  store: TranscriptStore
+  /** `provider/model` selection serving this session. */
+  model: string
+  /** Working-directory basename the session serves. */
+  cwd: string
+  /** Git branch name, empty outside a repository. */
+  branch: string
+  /** Short session identifier. */
+  sessionId: string
+  /** Submit one human prompt; the runner folds it into the session. */
+  onSubmit(text: string): void
+  /** Quit: unmount, flush, and request process exit. */
+  onQuit(): void
+}
+
+/** Ink `color` string for one palette triple. */
+function inkColor(triple: readonly [number, number, number]): string {
+  return `rgb(${triple[0]}, ${triple[1]}, ${triple[2]})`
+}
+
+/** One settled transcript row. */
+function EntryLine({ entry }: { entry: TranscriptEntry }): ReactElement {
+  switch (entry.kind) {
+    case 'user':
+      return createElement(Text, null, brand('❯ '), entry.text)
+    case 'assistant':
+      return createElement(Text, null, entry.text)
+    case 'tool': {
+      const mark = entry.state === 'running'
+        ? createElement(Text, { color: inkColor(TUI_RGB.brandBright) }, '◐')
+        : entry.state === 'error'
+          ? createElement(Text, { color: inkColor(TUI_RGB.error) }, '⨯')
+          : createElement(Text, { color: inkColor(TUI_RGB.success) }, '⏺')
+      return createElement(
+        Text,
+        null,
+        mark,
+        ' ',
+        brand(entry.name),
+        entry.summary === '' ? '' : ` ${dim(entry.summary)}`,
+      )
+    }
+    case 'error':
+      return createElement(Text, null, paintError(entry.text))
+    default:
+      return assertNever(entry, 'transcript entry kind')
+  }
+}
+
+/** The whale wordmark header in DeepSeek blue, hugging its content width. */
+function Header(): ReactElement {
+  return createElement(
+    Box,
+    // alignSelf shrinks the border to the whale-plus-wordmark content instead
+    // of stretching across the terminal and stranding empty space on the right
+    // (the compact-banner treatment the Claude Code welcome uses).
+    { flexDirection: 'row', gap: 1, borderStyle: 'round', borderColor: inkColor(TUI_RGB.brand), paddingX: 1, alignSelf: 'flex-start' },
+    createElement(
+      Box,
+      { flexDirection: 'column', width: WHALE_GLYPH_COLUMNS },
+      ...WHALE_GLYPH.map((row, index) => createElement(Text, { key: index, color: inkColor(TUI_RGB.brand) }, row)),
+    ),
+    createElement(
+      Box,
+      { flexDirection: 'column', justifyContent: 'center' },
+      createElement(Text, { color: inkColor(TUI_RGB.brand), bold: true }, 'DeepSeek Harness'),
+      createElement(Text, { dimColor: true }, '/help commands · Ctrl+C quit'),
+    ),
+  )
+}
+
+/**
+ * The footer status line: Claude-Code-style identity facts (model, working
+ * directory, git branch, session) beside the web composer's session figures
+ * (turns/steps, model and tool wall time, cache hit, token totals), joined
+ * by brand-colored pipes.
+ */
+function StatusLine({ facts, stats, busy }: {
+  facts: StatusFacts
+  stats: Parameters<typeof buildStatusGroups>[1]
+  busy: boolean
+}): ReactElement {
+  const groups = buildStatusGroups(facts, stats)
+  const children: ReactElement[] = [
+    busy
+      ? createElement(Text, { color: inkColor(TUI_RGB.brandBright) }, '● ')
+      : createElement(Text, { color: inkColor(TUI_RGB.brand) }, '○ '),
+  ]
+  groups.forEach((group, index) => {
+    if (index > 0) children.push(createElement(Text, { dimColor: true }, dim(' | ')))
+    children.push(createElement(Text, { dimColor: true }, group))
+  })
+  return createElement(Box, { paddingX: 1 }, ...children)
+}
+
+/** The prompt box: slash commands handled locally, other text submitted. */
+function Input({ busy, onSubmit, onQuit }: {
+  busy: boolean
+  onSubmit(text: string): void
+  onQuit(): void
+}): ReactElement {
+  const [value, setValue] = useState('')
+  const [notices, setNotices] = useState<readonly string[]>([])
+  useInput((input, key) => {
+    if (key.ctrl && (input === 'c' || input === 'd')) {
+      onQuit()
+      return
+    }
+    if (key.return) {
+      const text = value.trim()
+      setValue('')
+      if (text === '') return
+      if (text === '/quit') {
+        onQuit()
+        return
+      }
+      if (text === '/help') {
+        setNotices([...notices, '/help show commands · /clear clear the screen · /quit exit'])
+        return
+      }
+      if (text === '/clear') {
+        setNotices([])
+        console.clear()
+        return
+      }
+      if (busy) {
+        setNotices([...notices, 'the agent is working — wait for the turn to finish'])
+        return
+      }
+      onSubmit(text)
+      return
+    }
+    if (key.backspace || key.delete) {
+      setValue(value.slice(0, -1))
+      return
+    }
+    if (input !== '') {
+      setValue(value + input)
+    }
+  })
+  return createElement(
+    Box,
+    { flexDirection: 'column' },
+    ...notices.map((notice, index) => createElement(Text, { key: index, dimColor: true }, notice)),
+    createElement(
+      Box,
+      null,
+      createElement(Text, { color: inkColor(TUI_RGB.brand) }, busy ? '… ' : '❯ '),
+      createElement(Text, null, value),
+    ),
+  )
+}
+
+/** The whole terminal app; state arrives via the store, output via Ink. */
+export function App({ store, model, cwd, branch, sessionId, onSubmit, onQuit }: AppProps): ReactElement {
+  const view = useSyncExternalStore(store.subscribe, store.getView)
+  return createElement(
+    Box,
+    { flexDirection: 'column' },
+    createElement(Header),
+    createElement(
+      Box,
+      { flexDirection: 'column', paddingX: 1 },
+      ...view.entries.map((entry, index) => createElement(EntryLine, { key: index, entry })),
+      view.streaming !== '' ? createElement(Text, null, view.streaming) : undefined,
+      view.busy && view.streaming === '' ? createElement(Text, { dimColor: true }, 'thinking…') : undefined,
+    ),
+    createElement(Input, { busy: view.busy, onSubmit, onQuit }),
+    createElement(StatusLine, {
+      facts: { model, cwd, branch, sessionId },
+      stats: view.stats,
+      busy: view.busy,
+    }),
+  )
+}