codsh-cli 0.2.0 → 0.4.0

package/lib/types/editor.d.ts

@@ -1,186 +0,0 @@
-/**
- * The prompt's editing model: a multi-line buffer, a cursor, history, and the
- * completion menu.
- *
- * Pure state. It takes keys and answers with what changed, so every behaviour
- * here is testable without a terminal — the rendering and the raw-mode plumbing
- * are somebody else's job.
- * @module codsh-cli/src/editor
- */
-import type { CompletableCommand, CompletionResult } from './completion.ts';
-import type { Key } from './keys.ts';
-/** One entry offered in the completion menu. */
-export interface Candidate {
-    /** The text that replaces the token when accepted. */
-    value: string;
-    /** What it does, shown beside it. Empty for a path, which explains itself. */
-    detail: string;
-}
-/** What the editor is showing right now. */
-export interface EditorView {
-    /** Buffer lines; always at least one, possibly empty. */
-    lines: readonly string[];
-    /** Cursor line index. */
-    row: number;
-    /** Cursor column within that line, in code points. */
-    column: number;
-    /** Candidates to offer, empty when the menu is closed. */
-    candidates: readonly Candidate[];
-    /** Which candidate is selected, meaningless when there are none. */
-    selected: number;
-    /** The token under the cursor, which is what the candidates matched. */
-    token: string;
-}
-/** What the caller must do after a key. */
-export type EditorAction = {
-    kind: 'none';
-} | {
-    kind: 'submit';
-    text: string;
-} | {
-    kind: 'interrupt';
-} | {
-    kind: 'eof';
-} | {
-    kind: 'escape';
-};
-/** How the editor finds candidates for the token under the cursor. */
-export interface EditorSources {
-    /** The commands currently registered. */
-    commands(): readonly CompletableCommand[];
-    /** Path candidates for an `@` mention, as the completer produces them. */
-    paths(token: string): CompletionResult;
-    /**
-     * Argument candidates for one command's first argument.
-     *
-     * `/plan off`, `/permission workspace-write`, `/model <id>` — the values a
-     * command takes are the command's own knowledge, so the editor asks rather
-     * than guessing. Absent or empty means the argument is free-form.
-     * @param command - the command name without its slash.
-     * @param typed - what has been typed of the argument so far.
-     * @returns candidates to offer, best first.
-     */
-    commandArguments?(command: string, typed: string): readonly Candidate[];
-}
-/** A multi-line prompt editor. */
-export declare class Editor {
-    private readonly sources;
-    private lines;
-    private row;
-    private column;
-    private candidates;
-    private selected;
-    private readonly history;
-    /** Where the caller is in history; equals `history.length` when not browsing. */
-    private browsing;
-    /** The buffer set aside while history is being browsed. */
-    private stashed;
-    constructor(sources: EditorSources);
-    /** What to render. */
-    get view(): EditorView;
-    /** The buffer as one string. */
-    get text(): string;
-    /** Whether nothing has been typed. */
-    get empty(): boolean;
-    /**
-     * Replace the buffer with earlier text, cursor at its end.
-     *
-     * This is recall-for-editing: the second Escape puts the previous submission
-     * back so it can be corrected and resent.
-     * @param text - the text to edit, possibly multi-line.
-     */
-    prefill(text: string): void;
-    /** Submissions this session recorded, oldest first, for persistence. */
-    get pastSubmissions(): readonly string[];
-    /**
-     * Preload history from an earlier session.
-     *
-     * Applied before any live submission, so recall starts where the last
-     * session ended rather than empty.
-     * @param entries - past submissions, oldest first.
-     */
-    seedHistory(entries: readonly string[]): void;
-    /**
-     * Apply one key.
-     * @param key - the decoded keystroke.
-     * @returns what the caller must do about it.
-     */
-    handle(key: Key): EditorAction;
-    /** The line the cursor is on. */
-    private line;
-    /** Replace the cursor's line. */
-    private setLine;
-    /**
-     * Insert text at the cursor, splitting lines on newlines.
-     * @param text - the text to insert.
-     * @returns always `none`; insertion never completes a read.
-     */
-    private insert;
-    /**
-     * Submit, or accept the highlighted candidate when the menu is open.
-     * @returns the submission, or `none` when a candidate was taken instead.
-     */
-    private accept;
-    /** Record a submission for history, collapsing an immediate repeat. */
-    private remember;
-    /**
-     * Open the menu, or move through it when it is already open.
-     * @returns always `none`.
-     */
-    private complete;
-    /**
-     * Replace the token under the cursor with the selected candidate.
-     * @returns always `none`.
-     */
-    private take;
-    /** Where the token under the cursor begins, in code points. */
-    private tokenStart;
-    /** The token under the cursor. */
-    private token;
-    /**
-     * Recompute the candidate list for the token under the cursor.
-     *
-     * Recomputed on every edit rather than only on Tab, which is what makes the
-     * menu appear as a command is typed instead of after a key that asks for it.
-     */
-    private refresh;
-    /** Remove the character before the cursor, joining lines at a boundary. */
-    private backspace;
-    /** Remove the character after the cursor, joining lines at a boundary. */
-    private forwardDelete;
-    /** Move up a line, or back through history from the first line. */
-    private moveUp;
-    /** Move down a line, or forward through history from the last line. */
-    private moveDown;
-    /**
-     * Step through history.
-     * @param delta - -1 for older, 1 for newer.
-     * @returns always `none`.
-     */
-    private recall;
-    /** Move the cursor one position left, wrapping to the previous line. */
-    private moveLeft;
-    /** Move the cursor one position right, wrapping to the next line. */
-    private moveRight;
-    /**
-     * Put the cursor at a column on the current line.
-     * @param column - the target column.
-     * @returns always `none`.
-     */
-    private jump;
-    /** Drop everything after the cursor on this line. */
-    private killLine;
-    /** Drop everything before the cursor on this line. */
-    private killInput;
-    /** Move the cursor to the start of the word before it. */
-    private wordLeft;
-    /** Move the cursor past the end of the word after it. */
-    private wordRight;
-    /** Drop the word before the cursor. */
-    private killWord;
-    /**
-     * Close the menu, or report Escape when there is none to close.
-     * @returns `none` when a menu was dismissed, otherwise `escape`.
-     */
-    private cancel;
-}

package/lib/types/index.d.ts

@@ -1,48 +0,0 @@
-/**
- * `codsh` — the interactive terminal surface. The bundle
- * patch rides over dsh-base without Host, HTTP, or browser plugins; this runner
- * composes one Agent from the roster's preset, renders its session log to the
- * terminal, answers approvals and questions from the keyboard, and drives the
- * conversation until the person leaves.
- *
- * The surface shares the process with the Agent, so it reads `ctx.agents`
- * directly. The API gateway exists to carry out-of-process clients and would
- * add a serialization hop with no reader on the other side.
- *
- * @module codsh
- */
-import type { Context } from '@deepseek-ai/cordis';
-import z from '@deepseek-ai/schemastery';
-/** Stable Cordis plugin name. */
-export declare const name = "coding-cli-runner";
-/** Core services required before the surface can compose an agent. */
-export declare const inject: string[];
-/** Plugin config: the invocation resolved from this app's injected provider service. */
-export interface Config {
-    /** Opening task, or the empty string to start at the prompt. */
-    task: string;
-    /** Session to reopen: an id, `'latest'`, 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 to `task` and exit rather than entering the prompt. */
-    print: boolean;
-    /** Ring the terminal bell when a decision waits or a long turn ends. */
-    bell: boolean;
-    /** How long a `!` passthrough command may run before it is killed. */
-    bangTimeoutMs: number;
-    /** Output lines a `!` passthrough keeps before summarizing the rest. */
-    bangOutputLines: number;
-}
-export declare const Config: z<Config>;
-/** The process streams the surface binds to; tests substitute captures. */
-export declare const internals: {
-    input: NodeJS.ReadableStream;
-    output: NodeJS.WriteStream;
-};
-/**
- * Mount the interactive terminal surface.
- * @param ctx - plugin context carrying core services and the launcher-provided exit request.
- * @param config - validated invocation config.
- */
-export declare function apply(ctx: Context, config: Config): void;

package/lib/types/inputbox.d.ts

@@ -1,45 +0,0 @@
-/**
- * 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

@@ -1,15 +0,0 @@
-/**
- * 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

@@ -1,123 +0,0 @@
-/**
- * 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: '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 {
-    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

@@ -1,73 +0,0 @@
-/**
- * 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

@@ -1,34 +0,0 @@
-/**
- * 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

@@ -1,150 +0,0 @@
-/**
- * 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;
-    /** 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. */
-    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;
-    /** 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
-     * 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;
-    /**
-     * 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.
-     */
-    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;
-}