codsh-cli 0.1.0

package/lib/types/inputbox.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The input box: a framed, multi-line prompt that wraps long lines, grows with
+ * its content, and windows when it grows past its budget — with the completion
+ * menu under it.
+ *
+ * Pure layout. It turns an {@link EditorView} into the rows of the bottom region
+ * and says where the terminal cursor belongs, so the drawing code has no opinion
+ * about editing and this file has none about terminals.
+ *
+ * Wrapping is by display width, hard at the boundary: a wrap that respected word
+ * breaks would need the same word knowledge in the cursor mapping, and a cursor
+ * that disagrees with the wrap by one cell is worse than a word split across
+ * rows. Text is never truncated here — hiding typed text is how an input box
+ * loses a person's work.
+ * @module codsh-cli/src/inputbox
+ */
+import type { EditorView } from './editor.ts';
+import type { Theme } from './theme.ts';
+/** What the box is asked to show besides the buffer. */
+export interface BoxOptions {
+    /** Dim text shown inside an empty box, e.g. what `/` and `@` do. */
+    placeholder?: string | undefined;
+    /** Dim text shown under the box when the menu is closed. */
+    hint?: string | undefined;
+    /** Styles the frame; absent frames dim. A mode announces itself here. */
+    accent?: ((text: string) => string) | undefined;
+}
+/** The rows to draw and where the cursor goes among them. */
+export interface BoxLayout {
+    /** Rows, top to bottom, each already fitted to the terminal. */
+    rows: string[];
+    /** Index into {@link rows} where the cursor belongs. */
+    cursorRow: number;
+    /** Display column of the cursor on that row, from zero. */
+    cursorColumn: number;
+}
+/**
+ * Lay out the input box.
+ * @param view - what the editor is showing.
+ * @param theme - styling for the frame, the marker, and the menu.
+ * @param columns - display columns available.
+ * @param options - placeholder, hint, and frame accent.
+ * @returns the rows and cursor position.
+ */
+export declare function inputBox(view: EditorView, theme: Theme, columns: number, options?: BoxOptions): BoxLayout;

package/lib/types/invariant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package-owned invariant companion for `codsh-cli`.
+ * @module codsh-cli/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "coding-cli-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/keys.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Terminal bytes to key events.
+ *
+ * Owning the keyboard is what an input box costs: `readline` cannot report a
+ * lone Escape, cannot be asked to draw a completion menu, and decides for itself
+ * what Enter means. Decoding here is the price of deciding those things.
+ *
+ * The decoder is incremental because a terminal splits sequences across reads:
+ * an arrow key can arrive as `ESC`, then `[`, then `A`. Anything it cannot yet
+ * resolve is held until the next byte rather than guessed at.
+ * @module codsh-cli/src/keys
+ */
+/** What one keystroke means to the editor. */
+export type Key = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'enter';
+} | {
+    kind: 'newline';
+} | {
+    kind: 'tab';
+} | {
+    kind: 'backspace';
+} | {
+    kind: 'delete';
+} | {
+    kind: 'up';
+} | {
+    kind: 'down';
+} | {
+    kind: 'left';
+} | {
+    kind: 'right';
+} | {
+    kind: 'home';
+} | {
+    kind: 'end';
+} | {
+    kind: 'escape';
+} | {
+    kind: 'interrupt';
+} | {
+    kind: 'eof';
+} | {
+    kind: 'kill-line';
+} | {
+    kind: 'kill-input';
+} | {
+    kind: 'kill-word';
+} | {
+    kind: 'word-left';
+} | {
+    kind: 'word-right';
+} | {
+    kind: 'shift-tab';
+} | {
+    kind: 'clear-screen';
+} | {
+    kind: 'expand-output';
+} | {
+    kind: 'paste';
+    text: string;
+};
+/** Decodes terminal bytes into keys, holding partial sequences between reads. */
+export declare class KeyDecoder {
+    private held;
+    private pasting;
+    private pasted;
+    /**
+     * Feed one read's worth of input.
+     * @param chunk - the bytes as text.
+     * @returns the keys this read completed, in order.
+     */
+    push(chunk: string): Key[];
+    /** Whether bytes are held back awaiting the rest of a sequence. */
+    get pending(): boolean;
+    /**
+     * Resolve a held Escape that no further byte arrived for.
+     *
+     * `ESC` alone and the first byte of `ESC [ A` are the same byte, so the two can
+     * only be told apart by what follows — or by nothing following. The caller arms
+     * a short timer after each read and calls this when it expires: an arrow key
+     * split across reads completes long before that, and a key pressed by itself
+     * never completes at all.
+     * @returns the Escape key, or nothing when the held bytes are a real prefix.
+     */
+    flush(): Key[];
+    /**
+     * Resolve the held bytes into one key, if they are enough.
+     * @returns the keys produced, or undefined when more bytes are needed.
+     */
+    private take;
+    /**
+     * Collect bracketed-paste content up to its end marker.
+     * @returns the paste key once complete, otherwise undefined.
+     */
+    private takePasted;
+}
+/** Ask the terminal to wrap pasted text in markers. */
+export declare const ENABLE_PASTE_MARKERS = "\u001B[?2004h";
+/** Stop the terminal wrapping pasted text, restoring what it did before. */
+export declare const DISABLE_PASTE_MARKERS = "\u001B[?2004l";

package/lib/types/markdown.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Markdown as terminal lines.
+ *
+ * A model answers in Markdown, and printing the source verbatim leaves the
+ * reader to parse `**` and fences by eye. This renders the constructs that
+ * actually change how an answer reads — headings, lists, quotes, emphasis,
+ * inline code, and fenced blocks — and leaves everything else exactly as it
+ * arrived. Anything unrecognised must survive unchanged: mangling prose to
+ * decorate it is worse than not decorating it.
+ * @module codsh-cli/src/markdown
+ */
+import type { SyntaxTheme, Theme } from './theme.ts';
+/**
+ * Colour one line of code by token class.
+ *
+ * A heuristic, not a parser: it has no state between lines, so a string or
+ * comment spanning several lines is coloured only on the line where it opens.
+ * Getting that wrong costs a colour, never the text — every branch reproduces
+ * its input exactly.
+ * @param line - the code line.
+ * @param syntax - styling per token class.
+ * @returns the coloured line.
+ */
+export declare function highlightCode(line: string, syntax: SyntaxTheme): string;
+/**
+ * Style the inline constructs of one line of prose.
+ * @param text - the line, with block syntax already stripped.
+ * @param theme - styling for emphasis, code spans, and link targets.
+ * @returns the styled line.
+ */
+export declare function renderInline(text: string, theme: Theme): string;
+/**
+ * A Markdown renderer that consumes one line at a time.
+ *
+ * Stateful because fencing is: whether a line is code depends on a fence seen
+ * earlier, so a renderer that forgot between lines would style the inside of a
+ * code block as prose. This is the form streaming needs — a line can be
+ * rendered the moment it completes, without waiting for the whole answer.
+ */
+export interface MarkdownStream {
+    /**
+     * Render one input line.
+     * @param line - the line, without its terminator.
+     * @returns the output lines, which may be none (a fence delimiter, or a table
+     *   row held until the table ends).
+     */
+    line(line: string): string[];
+    /**
+     * Close the stream, rendering anything still held back.
+     *
+     * A table is only recognisable once its delimiter row arrives, so its rows
+     * buffer; an answer that ends mid-table must still show them.
+     * @returns the remaining output lines.
+     */
+    flush(): string[];
+    /** Whether the renderer is currently inside a fenced block. */
+    readonly inCode: boolean;
+}
+/**
+ * Build a line-at-a-time Markdown renderer.
+ * @param theme - styling for every construct.
+ * @param columns - display columns available, read per table; absent means
+ *   unconstrained. A table wider than this prints as its source lines.
+ * @returns the renderer, carrying its own fence and table state.
+ */
+export declare function createMarkdownStream(theme: Theme, columns?: () => number): MarkdownStream;
+/**
+ * Render a whole Markdown answer as terminal lines.
+ * @param text - the answer, as the model produced it.
+ * @param theme - styling for every construct.
+ * @returns the output lines, blocks included.
+ */
+export declare function renderMarkdown(text: string, theme: Theme): string[];

package/lib/types/preset-install.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Installing this bundle's own preset into the Harness home.
+ *
+ * The launcher owns the roster's `roots`: `composeProfile` overwrites that key
+ * with the installed app's shipped directory, so a bundle cannot contribute a
+ * search root of its own. What it can reach is the writable user root the
+ * roster appends by default, which is why a packaged preset is copied there
+ * rather than pointed at in place.
+ *
+ * The copy is idempotent and never overwrites: a preset a person edited — or
+ * one a newer package version would change — stays as it is, because the user
+ * root is theirs. Removing the directory restores the packaged copy.
+ * @module codsh-cli/src/preset-install
+ */
+/** The preset this bundle's patch names as the roster default. */
+export declare const PACKAGED_PRESET = "code-cli";
+/** What one install attempt did. */
+export interface PresetInstallResult {
+    /** Absolute directory the preset occupies after the attempt. */
+    path: string;
+    /** Whether this call created it; false when it was already present. */
+    installed: boolean;
+}
+/**
+ * Where {@link installPackagedPreset} puts the preset by default.
+ * @returns the absolute preset directory under the Harness home's user root.
+ */
+export declare function packagedPresetPath(): string;
+/**
+ * Copy the packaged preset into the user root unless it is already there.
+ * @param home - the user preset root; defaults to the Harness home's.
+ * @returns where the preset lives and whether this call wrote it.
+ */
+export declare function installPackagedPreset(home?: string): Promise<PresetInstallResult>;

package/lib/types/prompt.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The prompt as the person sees it: an input box, a completion menu, a working
+ * indicator, a status row, and — when a decision is being asked — a selection
+ * widget in the box's place.
+ *
+ * This is where the two input shapes meet. On a terminal it drives the editor
+ * from decoded keys and owns the bottom region; off one it reads lines from the
+ * pipe and draws nothing. Callers ask for the next submission either way.
+ * @module codsh-cli/src/prompt
+ */
+import type { TerminalConsole } from './console.ts';
+import type { EditorSources } from './editor.ts';
+import type { SelectOutcome, SelectSpec } from './selector.ts';
+import type { Theme } from './theme.ts';
+/** What the prompt reports to its owner. */
+export interface PromptHandlers {
+    /** Ctrl-C: stop the work, or leave. */
+    interrupt(): void;
+    /** Escape with nothing of the prompt's own to dismiss: stop the work. */
+    escape(): void;
+    /** Ctrl-D on an untouched prompt: leave. */
+    eof(): void;
+    /** Shift-Tab: cycle the session's mode. */
+    shiftTab?(): void;
+    /** Ctrl-O: show the last clipped tool output in full. */
+    expandOutput?(): void;
+}
+/** Drives the input box and answers reads and selections. */
+export declare class Prompt {
+    private readonly console;
+    private readonly theme;
+    private readonly handlers;
+    /** Dim text shown inside an empty box. */
+    private readonly placeholder?;
+    private readonly editor;
+    private pending;
+    private select_;
+    /**
+     * Submissions made before anything asked for them.
+     *
+     * Typing while the agent works — or in the instant before a read begins — must
+     * not be lost; the queue is what a line reader provides for free.
+     */
+    private readonly queued;
+    /** The working indicator shown under the box. */
+    private hint;
+    /** The always-current session facts shown as the region's last row. */
+    private status;
+    /** The assistant line still arriving, shown above the box. */
+    private streaming;
+    /** Frame styling for the current mode, e.g. plan mode's accent. */
+    private accent;
+    /** Whether a read is outstanding, which decides where a submission goes. */
+    private reading;
+    /**
+     * 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
+     * visible, and a prompt that vanishes for every turn reads as losing focus —
+     * so this is session-scoped, not read-scoped.
+     */
+    private engaged;
+    constructor(console: TerminalConsole, theme: Theme, sources: EditorSources, handlers: PromptHandlers, 
+    /** Dim text shown inside an empty box. */
+    placeholder?: string | undefined);
+    /** The editor's submission history, for persistence. */
+    get history(): readonly string[];
+    /**
+     * Preload history from an earlier session.
+     * @param entries - past submissions, oldest first.
+     */
+    seedHistory(entries: readonly string[]): void;
+    /** Whether the box holds no typed text. */
+    get empty(): boolean;
+    /**
+     * Show the input box from now on, independent of an outstanding read.
+     * @param engaged - whether the interactive session is running.
+     */
+    setEngaged(engaged: boolean): void;
+    /**
+     * Put earlier text back into the box for editing.
+     * @param text - the text to edit.
+     */
+    prefill(text: string): void;
+    /**
+     * Set the working indicator under the box.
+     * @param text - the text, or undefined to drop the row.
+     */
+    setHint(text: string | undefined): void;
+    /**
+     * Set the status row, the region's always-current last line.
+     * @param text - the styled row, or undefined to drop it.
+     */
+    setStatus(text: string | undefined): void;
+    /**
+     * Set the frame accent, which is how a mode shows on the box itself.
+     * @param accent - the styling, or undefined for the default frame.
+     */
+    setAccent(accent: ((text: string) => string) | undefined): void;
+    /**
+     * Set the assistant line currently arriving, shown above the box.
+     * @param text - the partial line, or undefined when none is open.
+     */
+    setStreaming(text: string | undefined): void;
+    /**
+     * Write one finished transcript line above the region.
+     * @param line - the line to keep.
+     */
+    write(line: string): void;
+    /**
+     * Wait for the next submitted text.
+     * @param signal - abandons the read, which an aborted tool call does.
+     * @returns the text, or undefined when input ended or the read was abandoned.
+     */
+    read(signal?: AbortSignal): Promise<string | undefined>;
+    /**
+     * Put one decision to the keyboard as an arrow-key selection.
+     *
+     * Only the terminal shape can offer this; the caller keeps a line-based
+     * fallback for pipes, where the selection keys cannot arrive.
+     * @param spec - the question and its options.
+     * @param signal - cancels the selection, which an aborted tool call does.
+     * @returns how the person decided.
+     */
+    select(spec: SelectSpec, signal?: AbortSignal): Promise<SelectOutcome>;
+    /** Take the region down, so what follows lands at the bottom of the screen. */
+    clear(): void;
+    /**
+     * Apply one key: control keys to the owner, a selection's keys to the
+     * selector, everything else to the editor.
+     * @param key - the decoded keystroke.
+     */
+    private onKey;
+    /** Recompose and redraw the bottom region. */
+    private render;
+}

package/lib/types/questions.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The terminal's user-questions provider: it renders each question as a
+ * numbered menu, reads one line per question, and encodes the answer.
+ *
+ * A question may offer options, free text, or both. Selecting by number
+ * answers with that option's label; typing anything else answers as `custom`,
+ * which is the encoding `ask_user_question` documents for an "Other" reply.
+ * @module codsh-cli/src/questions
+ */
+import type { AskUserQuestionAnswer, AskUserQuestionAnswerItem, AskUserQuestionItem, AskUserQuestionRequest } from '@deepseek-ai/dsh-user-questions';
+import type { SelectOutcome, SelectSpec } from './selector.ts';
+import type { Theme } from './theme.ts';
+/** Puts one selection to the keyboard; absent on a pipe, which types instead. */
+export type SelectAsk = (spec: SelectSpec, signal?: AbortSignal) => Promise<SelectOutcome>;
+/** Reads one answer from the person. */
+export interface LineReader {
+    /**
+     * Read one submission.
+     * @param signal - aborts the read when the owning tool call is cancelled.
+     * @returns the answer, or undefined when input ended or the read aborted.
+     */
+    read(signal?: AbortSignal): Promise<string | undefined>;
+}
+/**
+ * Parse a selection line against one question's options.
+ *
+ * A comma-separated list of numbers selects those options; a multi-select
+ * question accepts several, a single-select takes the first. Anything that is
+ * not a valid index becomes the free-text answer.
+ * @param line - the line the person typed.
+ * @param question - the question being answered.
+ * @returns the encoded answer for this question.
+ */
+export declare function encodeAnswer(line: string, question: AskUserQuestionItem): AskUserQuestionAnswerItem;
+/**
+ * Render one question as the lines shown above its prompt.
+ * @param question - the question to render.
+ * @param theme - styling for the heading and option list.
+ * @returns the lines to print.
+ */
+export declare function questionLines(question: AskUserQuestionItem, theme: Theme): string[];
+/** Answers `ask_user_question` from the terminal. */
+export declare class TerminalQuestions {
+    private readonly reader;
+    private readonly theme;
+    private readonly write;
+    /** The arrow-key selection, offered only where keys can arrive. */
+    private readonly select?;
+    constructor(reader: LineReader, theme: Theme, write: (line: string) => void, 
+    /** The arrow-key selection, offered only where keys can arrive. */
+    select?: SelectAsk | undefined);
+    /**
+     * Put every question in one request to the person, in order.
+     * @param request - the questions, owner agent, and abort signal.
+     * @returns one answer per question, in request order.
+     */
+    ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>;
+    /**
+     * Put one question to the person.
+     * @param question - the question.
+     * @param signal - aborts with the owning tool call.
+     * @returns the encoded answer.
+     */
+    private one;
+}

package/lib/types/selector.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The arrow-key selection widget: approvals, questions, and any other choice a
+ * person makes by moving a marker rather than by typing an answer.
+ *
+ * Pure state, like the editor: keys in, a verdict and rows out. One widget
+ * serves single-select, multi-select, and shortcut keys, because three slightly
+ * different pickers is how the same bug ships three times.
+ * @module codsh-cli/src/selector
+ */
+import type { Key } from './keys.ts';
+import type { Theme } from './theme.ts';
+/** One choice on offer. */
+export interface SelectOption {
+    /** What the choice is, shown as its row. */
+    label: string;
+    /** Extra context shown dimly beside the label. */
+    detail?: string;
+    /** Single key that picks this option outright (e.g. `y`). */
+    shortcut?: string;
+}
+/** What a selection asks. */
+export interface SelectSpec {
+    /** The question, shown above the options. */
+    title: string;
+    options: readonly SelectOption[];
+    /** Whether several options may be chosen; Space toggles, Enter confirms. */
+    multi?: boolean;
+    /** Label for a trailing "type your own" row; absent offers none. */
+    custom?: string;
+}
+/** How one selection ended. */
+export type SelectOutcome = {
+    kind: 'chosen';
+    indices: number[];
+} | {
+    kind: 'custom';
+} | {
+    kind: 'cancelled';
+};
+/** What a key did to the selection. */
+export type SelectorStep = {
+    kind: 'pending';
+} | {
+    kind: 'done';
+    outcome: SelectOutcome;
+};
+/** An in-progress selection. */
+export declare class Selector {
+    private readonly spec;
+    private selected;
+    private readonly checked;
+    constructor(spec: SelectSpec);
+    /** How many rows the widget offers, the custom row included. */
+    private get count();
+    /** Whether a row index is the custom "type your own" row. */
+    private isCustom;
+    /**
+     * Apply one key.
+     * @param key - the decoded keystroke.
+     * @returns whether the selection settled, and how.
+     */
+    handle(key: Key): SelectorStep;
+    /**
+     * Resolve a typed character: a digit jumps, a shortcut picks, Space toggles.
+     * @param text - what was typed.
+     * @returns whether the selection settled.
+     */
+    private typed;
+    /**
+     * Settle on a row.
+     * @param index - the row accepted.
+     * @returns the settled step.
+     */
+    private accept;
+    /**
+     * Render the widget.
+     * @param theme - styling for the marker, shortcuts, and details.
+     * @param columns - display columns available per row.
+     * @returns the rows, title first.
+     */
+    view(theme: Theme, columns: number): string[];
+    /**
+     * One option's label with its number and shortcut.
+     * @param option - the option to label.
+     * @param theme - styling for the shortcut.
+     * @returns the label text.
+     */
+    private label;
+    /**
+     * One rendered row.
+     * @param index - the row's index.
+     * @param label - the row's label, already styled.
+     * @param detail - dim context beside it.
+     * @param theme - styling for the marker and detail.
+     * @param columns - display columns available.
+     * @returns the row text.
+     */
+    private row;
+}

package/lib/types/spinner.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The working indicator: one rewritable line saying the agent is busy, how long
+ * it has been, and which key stops it.
+ *
+ * It occupies the console's single live line, so the transcript above it stays
+ * append-only and the indicator never survives into a redirected transcript.
+ * @module codsh-cli/src/spinner
+ */
+import type { Theme } from './theme.ts';
+/** The console surface a spinner drives. */
+export interface LiveSurface {
+    setLive(text: string | undefined): void;
+    readonly isTty: boolean;
+}
+/** Formats the indicator's text for one tick. */
+export interface SpinnerLabel {
+    /** What the agent is doing, e.g. `working`. */
+    verb: string;
+    /** Key that cancels, named for the surface that can read it. */
+    interrupt: string;
+    /** Live extra segment, read each tick — e.g. tokens spent so far. */
+    detail?: () => string | undefined;
+}
+/**
+ * Render one tick of the indicator.
+ * @param frame - the frame index, taken modulo the frame count.
+ * @param elapsedMs - milliseconds since the work started.
+ * @param label - the verb and interrupt key to name.
+ * @param theme - styling for the frame and the hint.
+ * @returns the line to display.
+ */
+export declare function spinnerText(frame: number, elapsedMs: number, label: SpinnerLabel, theme: Theme): string;
+/** Drives the working indicator for as long as the agent is busy. */
+export declare class Spinner {
+    private readonly surface;
+    private readonly theme;
+    private readonly label;
+    /** Injected so tests advance time without waiting for it. */
+    private readonly now;
+    private timer;
+    private frame;
+    private startedAt;
+    constructor(surface: LiveSurface, theme: Theme, label: SpinnerLabel, 
+    /** Injected so tests advance time without waiting for it. */
+    now?: () => number);
+    /** Whether the indicator is running. */
+    get running(): boolean;
+    /**
+     * Start the indicator, or do nothing when it is already running or the
+     * surface has no cursor to rewrite.
+     */
+    start(): void;
+    /** Stop the indicator and clear its line. */
+    stop(): void;
+    /** Paint the current frame. */
+    private draw;
+}

package/lib/types/startup.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The terminal app's command-line provider: it parses the optional task
+ * positional, the session-continuation flags, the preset override, and
+ * `--help`, then publishes {@link CODING_CLI_STARTUP_SERVICE}. The runner is an
+ * ordinary consumer whose lazy config waits for that service.
+ * @module codsh-cli/startup
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Stable Cordis plugin name. */
+export declare const name = "coding-cli-startup";
+/** Services required before the invocation can be resolved. */
+export declare const inject: string[];
+/** Service provided by this plugin and injected by the terminal runner. */
+export declare const CODING_CLI_STARTUP_SERVICE = "codingCliStartup";
+/** What the runner row reads from {@link CODING_CLI_STARTUP_SERVICE}. */
+export interface CodingCliStartupValues {
+    /** Opening task text, or the empty string when the session starts at the prompt. */
+    task: string;
+    /** Session to reopen: an explicit id, `'latest'` for `--continue`, or the empty string for a new session. */
+    resume: string;
+    /** Preset id overriding the roster default, or the empty string to accept it. */
+    preset: string;
+    /** Render the answer and exit rather than entering the interactive loop. */
+    print: boolean;
+}
+/**
+ * Parse and provide this invocation as an ordinary Cordis service. On `--help`
+ * and on a usage error nothing is provided, so the runner never mounts.
+ * @param ctx - plugin context carrying the command line.
+ */
+export declare function apply(ctx: Context): void;