codsh-cli 0.1.0 → 0.2.0

package/lib/types/console.d.ts

@@ -1,10 +1,12 @@
 /**
  * The process-facing terminal, in two shapes.
  *
- * On a terminal this surface owns the keyboard: raw mode, its own key decoding,
- * and a managed region of rows at the bottom holding the input box. That is what
- * an inline completion menu and a multi-line prompt require — `readline` reports
- * no lone Escape, draws no menu, and decides for itself what Enter means.
+ * On a terminal this surface owns the keyboard AND the screen: raw mode, its own
+ * key decoding, and an alternate-screen viewport ({@link Screen}) that holds the
+ * transcript in a scrollback buffer of its own with the input box pinned below
+ * it. That is what an inline completion menu, a multi-line prompt, and a session
+ * that reads as its own space require — `readline` reports no lone Escape, draws
+ * no menu, and decides for itself what Enter means.
  *
  * Off a terminal it is a line reader over `readline`, because a pipe has no
  * cursor to manage and every line in a script is a separate instruction. Both
@@ -16,6 +18,7 @@ import type { Key } from './keys.ts';
 /** The output stream this surface writes to. */
 export interface OutputStream extends NodeJS.WritableStream {
     readonly columns?: number;
+    readonly rows?: number;
     readonly isTTY?: boolean;
 }
 /** The input stream this surface reads from. */
@@ -41,15 +44,18 @@ export declare class TerminalConsole {
     private readonly earlyKeys;
     private escapeTimer;
     private ended;
-    /** Rows currently drawn in the bottom region. */
-    private regionRows;
-    /** Where among those rows the cursor was left. */
-    private regionCursor;
-    /** Whether the region currently holds input focus, which shows the cursor. */
-    private regionFocus;
+    /** The viewport this surface owns on a terminal; absent off one. */
+    private readonly screen;
     constructor(input: InputStream, output: OutputStream);
     /** Display columns available for one line, never below {@link MIN_COLUMNS}. */
     get columns(): number;
+    /**
+     * Columns content may be laid out for: one less than the width, because the
+     * viewport wraps at that boundary. Markdown layout MUST use this figure — a
+     * table laid out one column wider is refolded by the viewport, and its rows
+     * shear apart.
+     */
+    get contentColumns(): number;
     /** Whether the output stream is a terminal. */
     get isTty(): boolean;
     /**
@@ -69,10 +75,40 @@ export declare class TerminalConsole {
      */
     onResize(handler: () => void): () => void;
     /**
-     * Clear the visible screen.
+     * Take the viewport: the transcript and the prompt live on their own screen
+     * from here, and the terminal keeps the buffer the person had.
+     */
+    enterScreen(): void;
+    /**
+     * Give the terminal back. Idempotent: every exit path calls it.
+     */
+    leaveScreen(): void;
+    /** Whether this surface currently holds its own screen. */
+    get owningScreen(): boolean;
+    /**
+     * Scroll the transcript inside the viewport.
+     * @param delta - rows to move; negative goes back into history.
+     */
+    scrollBy(delta: number): void;
+    /**
+     * Set the notice shown while the transcript is scrolled back.
+     * @param text - the styled line, or the empty string for none.
+     */
+    setScrollNotice(text: string): void;
+    /**
+     * Scroll the transcript by a whole viewport.
+     * @param direction - -1 for back into history, 1 towards the tail.
+     */
+    scrollPage(direction: -1 | 1): void;
+    /** Return to the tail of the transcript. */
+    scrollToBottom(): void;
+    /** Physical rows currently scrolled out of view; zero means at the tail. */
+    get scrolledBy(): number;
+    /**
+     * Clear the transcript this session accumulated.
      *
-     * The scrollback survives — this wipes the viewport the way a shell's clear
-     * does. The managed region is forgotten with it, so the caller redraws.
+     * On its own screen there is no shell scrollback to preserve, so this empties
+     * the buffer the viewport shows rather than wiping a shared terminal.
      */
     clearScreen(): void;
     /**
@@ -98,39 +134,82 @@ export declare class TerminalConsole {
     /** Mark input finished and release every waiting read. */
     private end;
     /**
-     * Write one finished line above the managed region.
+     * Keep one finished transcript line.
      *
-     * The region is erased first and redrawn after, so the transcript stays
-     * append-only while the input box keeps its place at the bottom.
+     * On its own screen the line goes into the viewport's scrollback, which is
+     * what lets the transcript scroll under a prompt that does not move. Off one
+     * it is written straight out, because a pipe's reader wants exactly that.
      * @param line - the line, without its terminator.
      */
     write(line: string): void;
     /**
-     * Replace the managed region at the bottom of the screen.
+     * Replace the rows pinned below the transcript.
      *
      * This is the whole live area: an input box, a completion menu, a working
-     * indicator. Everything the transcript keeps goes through {@link write}
-     * instead, because a terminal cannot revise a row that has scrolled. Off a
-     * terminal the call is ignored — a redirected transcript must not collect
-     * frames of a box nobody can see.
+     * indicator, the status row. Off a terminal the call is ignored — a
+     * redirected transcript must not collect frames of a box nobody can see.
      * @param rows - the rows to display, top to bottom.
      * @param cursor - where to leave the terminal cursor among them.
-     * @param focus - whether the region holds input focus. Without it the cursor
-     *   stays hidden: a block cursor parked on a display row (the status line,
-     *   a streaming line) reads as content colliding with it.
+     * @param focus - whether the rows hold input focus, which is when the cursor
+     *   shows. Parked anywhere else it reads as content colliding with it.
      */
     setRegion(rows: readonly string[], cursor: RegionCursor, focus?: boolean): void;
-    /** Remove the region, leaving the cursor where the next write will land. */
-    clearRegion(): void;
-    /** Move to the region's first row and erase everything from there down. */
-    private eraseRegion;
     /**
-     * Draw rows from the cursor down and place the cursor among them.
-     * @param rows - the rows to draw.
-     * @param cursor - the target position.
-     * @param focus - whether to show the cursor at that position afterwards.
+     * Keep one collapsible block: summary now, full form behind the toggle.
+     *
+     * Off a terminal only the summary is written — a pipe has no keys to toggle
+     * with, and scripts want the digest.
+     * @param summary - the collapsed lines.
+     * @param full - the expanded lines.
+     */
+    appendFold(summary: readonly string[], full: readonly string[]): void;
+    /**
+     * Swap every collapsible block between summary and full form.
+     * @returns false when there is nothing to toggle.
      */
-    private drawRegion;
+    /**
+     * Anchor a mouse selection at a terminal position.
+     * @param row - terminal row, 1-based.
+     * @param column - terminal column, 1-based.
+     */
+    mouseDown(row: number, column: number): void;
+    /**
+     * Extend the mouse selection to a terminal position.
+     * @param row - terminal row, 1-based.
+     * @param column - terminal column, 1-based.
+     */
+    mouseDrag(row: number, column: number): void;
+    /**
+     * Finish the mouse selection.
+     * @returns the selected text, or undefined for a bare click.
+     */
+    mouseUp(): string | undefined;
+    /**
+     * Put text on the clipboard.
+     *
+     * Two channels, because neither is universal: OSC 52 reaches through SSH and
+     * works wherever the terminal permits it, and the platform helper covers the
+     * terminals that refuse the escape. `CODSH_CLIPBOARD` narrows it to `osc52`,
+     * `system`, or `off` — tests use `osc52` so a run never touches the real
+     * clipboard.
+     * @param text - the plain text to copy.
+     * @returns whether a copy was attempted at all.
+     */
+    copyText(text: string): boolean;
+    /**
+     * Make the last `count` written lines a collapsible block after the fact.
+     *
+     * Screen-only on purpose: a pipe already carries the full text, and a
+     * summary would subtract from it.
+     * @param count - how many trailing lines the block owns.
+     * @param summary - the collapsed lines, already styled.
+     */
+    foldRecent(count: number, summary: readonly string[]): void;
+    toggleFolds(): boolean;
+    /** Return every block to its summary. */
+    collapseFolds(): void;
+    /** Take the pinned rows down, leaving the transcript alone. */
+    clearRegion(): void;
     /** Ring the terminal bell; a pipe gets nothing to beep with. */
     bell(): void;
     /**
@@ -149,4 +228,13 @@ export declare class TerminalConsole {
     readLine(signal?: AbortSignal): Promise<string | undefined>;
     /** Restore the terminal and stop reading. */
     close(): void;
+    /**
+     * Write one line to the terminal the person keeps, not to our viewport.
+     *
+     * The exit summary is what needs this: the session's own screen disappears
+     * with it, so the few facts worth keeping — the session id, what it cost —
+     * have to land in the buffer that survives.
+     * @param line - the line, without its terminator.
+     */
+    writeAfterScreen(line: string): void;
 }

package/lib/types/keys.d.ts

@@ -58,9 +58,29 @@ export type Key = {
     kind: 'clear-screen';
 } | {
     kind: 'expand-output';
+} | {
+    kind: 'page';
+    direction: -1 | 1;
+} | {
+    kind: 'scroll';
+    lines: number;
+} | {
+    kind: 'scroll-end';
 } | {
     kind: 'paste';
     text: string;
+} | {
+    kind: 'mouse-down';
+    row: number;
+    column: number;
+} | {
+    kind: 'mouse-drag';
+    row: number;
+    column: number;
+} | {
+    kind: 'mouse-up';
+    row: number;
+    column: number;
 };
 /** Decodes terminal bytes into keys, holding partial sequences between reads. */
 export declare class KeyDecoder {

package/lib/types/prompt.d.ts

@@ -44,6 +44,9 @@ export declare class Prompt {
     private readonly queued;
     /** The working indicator shown under the box. */
     private hint;
+    /** A short-lived notice that borrows the hint row, e.g. the copy toast. */
+    private flash;
+    private flashTimer;
     /** The always-current session facts shown as the region's last row. */
     private status;
     /** The assistant line still arriving, shown above the box. */
@@ -52,6 +55,9 @@ export declare class Prompt {
     private accent;
     /** Whether a read is outstanding, which decides where a submission goes. */
     private reading;
+    /** Wheel rows accumulated this tick, painted once — scrolling per event janks. */
+    private pendingScroll;
+    private scrollFlushQueued;
     /**
      * Whether the interactive session is running, which is when the box is worth
      * drawing. The box stays up while the agent works — typing ahead must be
@@ -86,6 +92,15 @@ export declare class Prompt {
      * @param text - the text, or undefined to drop the row.
      */
     setHint(text: string | undefined): void;
+    /**
+     * Show a notice on the hint row briefly, then give the row back.
+     *
+     * The hint row belongs to the working indicator, which repaints itself
+     * continuously — a notice written through setHint would last one tick. The
+     * flash outranks the hint until its moment passes.
+     * @param text - the styled notice.
+     */
+    setFlash(text: string): void;
     /**
      * Set the status row, the region's always-current last line.
      * @param text - the styled row, or undefined to drop it.

package/lib/types/screen.d.ts

@@ -0,0 +1,204 @@
+/**
+ * The session's own screen: an alternate-screen viewport with its own scrollback.
+ *
+ * This is what makes a session feel like a place rather than a run of output.
+ * The terminal's buffer is left exactly as the person had it — their shell
+ * history is neither scrolled away nor interleaved — and everything this
+ * surface shows lives in a buffer it owns: the transcript scrolls inside the
+ * viewport while the input box stays where it is, at the bottom.
+ *
+ * Owning the viewport means doing three jobs the terminal used to do. Lines are
+ * wrapped here ({@link wrapAll}), because a line that overflows would otherwise
+ * overwrite the row below. Scrolling is ours, because the terminal's scrollback
+ * does not exist on the alternate screen. And every frame is painted as a
+ * whole, diffed against the last one — which is what removes the class of bug
+ * that relative erase arithmetic keeps producing.
+ * @module codsh/src/screen
+ */
+/** Where the cursor belongs within the chrome rows. */
+export interface ChromeCursor {
+    row: number;
+    column: number;
+}
+/** What the screen writes to and measures itself against. */
+export interface ScreenHost {
+    /** Emit raw bytes to the terminal. */
+    write(data: string): void;
+    /** Display columns currently available. */
+    columns(): number;
+    /** Screen rows currently available. */
+    rows(): number;
+}
+/** An alternate-screen viewport over a scrollback buffer this surface owns. */
+export declare class Screen {
+    private readonly host;
+    /** Logical transcript lines, unwrapped, oldest first. */
+    private logical;
+    /** The same lines wrapped to the current width — what the viewport slices. */
+    private physical;
+    /** The bottom rows: input box, menu, indicator, status. */
+    private chrome;
+    private chromeCursor;
+    /** Whether the chrome holds input focus, which is when the cursor shows. */
+    private chromeFocus;
+    /** Physical rows hidden below the viewport; zero means following the tail. */
+    private offset;
+    /** What to show while scrolled back, drawn over the viewport's top row. */
+    private notice;
+    /** A mouse selection over the transcript, in physical-row coordinates. */
+    private selection;
+    /** Collapsed blocks in the transcript, in order, with both of their forms. */
+    private folds;
+    /** Whether the folds currently show their full form. */
+    private expanded;
+    /** The last painted frame, so a repaint only touches rows that changed. */
+    private painted;
+    /** Width the current frame was painted at, to detect a resize. */
+    private paintedColumns;
+    private active;
+    constructor(host: ScreenHost);
+    /** Whether the alternate screen is currently held. */
+    get entered(): boolean;
+    /** Physical rows scrolled up out of view; zero means the tail is showing. */
+    get scrolledBy(): number;
+    /** Take the alternate screen and start reporting the mouse. */
+    enter(): void;
+    /**
+     * Give the terminal back exactly as it was.
+     *
+     * Idempotent, because every exit path calls it — a normal quit, an
+     * interrupt, and a crash handler all have to leave the terminal usable.
+     */
+    leave(): void;
+    /**
+     * Append finished transcript lines.
+     *
+     * Following the tail is the default; a person who has scrolled up stays
+     * where they are, and the new rows accumulate below them.
+     * @param lines - the lines to keep, already styled.
+     */
+    append(lines: readonly string[]): void;
+    /**
+     * Append one collapsible block: its summary now, its full form on demand.
+     *
+     * This is what makes every long block — not merely the latest — expandable:
+     * the buffer keeps both forms, and toggling rebuilds the transcript in
+     * place, exactly like a details/summary element.
+     * @param summary - the collapsed lines, already styled.
+     * @param full - the expanded lines, already styled.
+     */
+    appendFold(summary: readonly string[], full: readonly string[]): void;
+    /**
+     * Turn the last `count` appended lines into a collapsible block after the
+     * fact.
+     *
+     * This is how a finished answer becomes foldable without ever having been
+     * withheld: it streamed in the open, and only once complete does it grow a
+     * summary form. The block starts expanded — the person is reading it — and
+     * collapses with the rest when the conversation moves on.
+     * @param count - how many trailing lines the block owns.
+     * @param summary - the collapsed lines, already styled.
+     */
+    foldBack(count: number, summary: readonly string[]): void;
+    /** Whether any collapsible block exists. */
+    get hasFolds(): boolean;
+    /** Whether the folds currently show their full form. */
+    get foldsExpanded(): boolean;
+    /**
+     * Swap every fold between its summary and its full form.
+     * @returns false when there is nothing to toggle.
+     */
+    toggleFolds(): boolean;
+    /** Return every fold to its summary, the way moving on reads as dismissal. */
+    collapseFolds(): void;
+    /** Put every fold into one form, whatever mix of states they are in now. */
+    private setFolds;
+    /**
+     * Replace the bottom rows.
+     * @param rows - the chrome, top to bottom.
+     * @param cursor - where the cursor belongs among them.
+     * @param focus - whether to show the cursor there.
+     */
+    setChrome(rows: readonly string[], cursor: ChromeCursor, focus: boolean): void;
+    /**
+     * Set the line shown while the reader is away from the tail.
+     *
+     * Drawn OVER the viewport's top row rather than added to the chrome: a notice
+     * that changed the chrome's height would move the input box as a side effect
+     * of scrolling, and would make a page up and a page down different sizes.
+     * @param text - the styled notice, already fitted.
+     */
+    setScrollNotice(text: string): void;
+    /**
+     * Scroll the transcript.
+     * @param delta - rows to move; negative scrolls back into history.
+     */
+    scrollBy(delta: number): void;
+    /**
+     * Scroll by a whole viewport, which is what the page keys mean.
+     * @param direction - -1 for back into history, 1 towards the tail.
+     */
+    scrollPage(direction: -1 | 1): void;
+    /** Jump back to the tail, which is also what a new submission does. */
+    scrollToBottom(): void;
+    /**
+     * Drop the transcript, keeping the chrome.
+     *
+     * Ctrl-L on a shared terminal clears a viewport the person may want back; on
+     * our own screen the buffer IS the session's history, so this empties it.
+     */
+    clearTranscript(): void;
+    /** Re-wrap and repaint after the terminal changed size. */
+    resize(): void;
+    /**
+     * Anchor a selection where the left button went down.
+     *
+     * The terminal cannot select for us while mouse reporting is on, so the
+     * viewport does it: press anchors, motion extends, release copies — the
+     * shape opencode and Claude give the same gesture.
+     * @param row - terminal row, 1-based.
+     * @param column - terminal column, 1-based.
+     */
+    mouseDown(row: number, column: number): void;
+    /**
+     * Extend the selection to where the pointer moved.
+     * @param row - terminal row, 1-based.
+     * @param column - terminal column, 1-based.
+     */
+    mouseDrag(row: number, column: number): void;
+    /**
+     * Finish the gesture.
+     *
+     * The highlight stays up — the copy already happened, and the marks show
+     * what it took — until the next click or reflow dismisses it.
+     * @returns the selected text, or undefined for a bare click.
+     */
+    mouseUp(): string | undefined;
+    /** The selection's bounds in order, top-left first. */
+    private orderedSelection;
+    /** The plain text under the selection, visual rows joined by newlines. */
+    private selectedText;
+    /**
+     * Map a terminal position to a physical buffer position.
+     * @param row - terminal row, 1-based.
+     * @param column - terminal column, 1-based.
+     * @param clamp - pull an outside position to the nearest content row, the
+     * way dragging past an edge keeps selecting, instead of refusing it.
+     * @returns the position, or undefined when it misses the content.
+     */
+    private locate;
+    /** Rows the transcript viewport occupies. */
+    private viewportHeight;
+    /** Columns content is laid out for, one short of the width so no row wraps. */
+    private contentColumns;
+    /** Re-wrap every kept line at the current width. */
+    private rewrap;
+    /**
+     * Compose and paint the frame.
+     *
+     * The viewport is padded at the top when the transcript is shorter than the
+     * screen, which is what puts the chrome at the bottom from the first frame
+     * rather than wherever output happened to reach.
+     */
+    private render;
+}

package/lib/types/selector.d.ts

@@ -44,7 +44,6 @@ export type SelectorStep = {
     kind: 'done';
     outcome: SelectOutcome;
 };
-/** An in-progress selection. */
 export declare class Selector {
     private readonly spec;
     private selected;

package/lib/types/spinner.d.ts

@@ -48,9 +48,15 @@ export declare class Spinner {
     /**
      * Start the indicator, or do nothing when it is already running or the
      * surface has no cursor to rewrite.
+     *
+     * The clock keeps running across a pause: the elapsed figure is the whole
+     * turn's, and an indicator that restarted from zero at every tool call would
+     * report each step instead.
      */
     start(): void;
-    /** Stop the indicator and clear its line. */
+    /** Hide the indicator without forgetting when the turn began. */
+    pause(): void;
+    /** Stop the indicator: the turn is over, and the next one starts at zero. */
     stop(): void;
     /** Paint the current frame. */
     private draw;

package/lib/types/theme.d.ts

@@ -50,11 +50,12 @@ export declare function createTheme(isTty: boolean, env: Record<string, string |
 /**
  * Display columns a string occupies once printed, ignoring styling sequences.
  *
- * Combining marks are counted as zero and East Asian Wide/Fullwidth code
- * points as two, which is what a terminal's own cursor arithmetic does. This
- * covers the alignment and wrapping this surface needs; it is not a complete
- * grapheme segmenter, so a ZWJ emoji sequence still counts each joined code
- * point ({@link ../README.md | Known Limitations}).
+ * Measured by `string-width` — the width authority cli-table3, ink, and every
+ * maintained terminal renderer sit on — so East Asian Wide, emoji presentation
+ * (`⚡` included), combining marks, and ZWJ sequences all match what a
+ * terminal's cursor actually does. A hand-kept range table here mis-sized `⚡`
+ * and sheared a real table's columns; widths are exactly the kind of data
+ * nobody should maintain by hand.
  * @param text - the string to measure, possibly carrying SGR sequences.
  * @returns the number of display columns.
  */

package/lib/types/transcript.d.ts

@@ -42,8 +42,8 @@ export declare class Transcript {
     private readonly options;
     private readonly presenters;
     private readonly calls;
-    /** The most recent result whose body the cap clipped, kept in full. */
-    private clipped;
+    /** The full form of the event just rendered, when its body was collapsed. */
+    private fold;
     constructor(options: TranscriptOptions, presenters: ToolPresenters);
     /**
      * Shorten an absolute path inside the workspace to a workspace-relative one.
@@ -88,14 +88,14 @@ export declare class Transcript {
      */
     private renderResult;
     /**
-     * The last clipped result, rendered without its cap.
-     *
-     * Ctrl-O's answer. The full body is kept from the render itself because a
-     * tool's own output limits are upstream of the log — this is everything the
-     * model saw, which is everything recoverable.
-     * @returns the header and full body, or undefined when nothing was clipped.
+     * The expanded form of the lines {@link render} just returned, when that
+     * event's body was collapsed — the whole event re-rendered without its cap,
+     * because a fold swaps entire blocks, not just the clipped tail. The full
+     * body is kept from the render itself: what a tool truncated before
+     * returning is upstream of the log and unrecoverable everywhere.
+     * @returns the full lines, or undefined when nothing was collapsed.
      */
-    expandLast(): string[] | undefined;
+    takeFold(): string[] | undefined;
     /**
      * Render one completed call's status suffix and body from its declared view.
      * @param view - the result view, absent when no presenter answered.

package/lib/types/wrap.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Display-width wrapping for styled text.
+ *
+ * Inside the alternate screen the terminal no longer wraps for us: a transcript
+ * line longer than the viewport must be broken into rows before it is painted,
+ * or it would overwrite the row below. The lines being broken are already
+ * styled, so a naive split would cut an escape sequence in half and leak
+ * gibberish — and a continuation row would lose the colour its first half set.
+ * @module codsh/src/wrap
+ */
+/**
+ * Break one styled line into rows no wider than `columns` display columns.
+ *
+ * Styles carry across the break: each continuation row re-opens whatever was
+ * active where the cut fell, and every row that opened a style closes it.
+ * @param text - the styled line, without a terminator.
+ * @param columns - display columns available per row.
+ * @returns the rows, at least one (an empty line yields one empty row).
+ */
+export declare function wrapStyled(text: string, columns: number): string[];
+/**
+ * Wrap many lines, keeping their order.
+ * @param lines - styled lines.
+ * @param columns - display columns per row.
+ * @returns the physical rows they occupy.
+ */
+export declare function wrapAll(lines: readonly string[], columns: number): string[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codsh-cli",
   "description": "A Claude Code-style coding agent for the terminal, composed on the DeepSeek Harness (dsh): interactive TTY surface, plan mode, approvals, custom commands, and session management over the dsh plugin runtime",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -75,7 +75,8 @@
     "@deepseek-ai/dsh-workflow-worker-thread": "^0.1.0-rc.7",
     "@deepseek-ai/schemastery": "^3.18.1",
     "commander": "^15.0.0",
-    "diff": "^9.0.0"
+    "diff": "^9.0.0",
+    "string-width": "^8.2.2"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
@@ -144,6 +145,7 @@
     "test": "vitest run",
     "test:e2e": "pnpm run build && vitest run --config vitest.e2e.config.ts",
     "dev": "node scripts/dev.mjs",
+    "sync:dsh": "node scripts/sync-dsh.mjs",
     "release": "pnpm run build && changeset publish"
   }
 }