codsh-bundle 0.3.0

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region src/invariant.ts
+const PACKAGE_NAME = "codsh-bundle";
+/** Cordis companion plugin name. */
+const name = "coding-cli-invariant";
+/** Service required before the companion can register. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the surface is a renderer and input loop over the
+* session log whose observable contract (rendered transcript, approval
+* decisions, exit code) is process-level and owned by the launcher e2e. It
+* holds no durable relation of its own — every fact it shows is derived from
+* `session/event`, whose relations `dsh-session` already audits.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+
+//#endregion
+export { apply, inject, name };

package/lib/startup.js

@@ -0,0 +1,64 @@
+import { Command } from "commander";
+import { parseCmdline } from "@deepseek-ai/dsh-cmdline";
+
+//#region src/startup.ts
+/** Stable Cordis plugin name. */
+const name = "coding-cli-startup";
+/** Services required before the invocation can be resolved. */
+const inject = ["cmdlineArgs"];
+/** Service provided by this plugin and injected by the terminal runner. */
+const CODING_CLI_STARTUP_SERVICE = "codingCliStartup";
+/**
+* This app's command: the optional task positional, its flags, and its help text.
+* @returns a fresh program, so one process can parse more than once (tests).
+*/
+function codingCliCommand() {
+	return new Command().name("dsh code").description("Work through coding tasks in an interactive terminal session.").helpOption("-h, --help", "show this help").argument("[task...]", "opening task; multiple words are joined by spaces. Omit it to start at the prompt").option("--resume <session>", "reopen a session by id and continue its conversation").option("--continue", "reopen the most recent session in this working directory").option("--preset <id>", "compose the agent from this preset instead of the roster default").option("-p, --print", "render the answer to the opening task and exit without entering the prompt").addHelpText("after", `
+Examples:
+  dsh code                                   start an interactive session
+  dsh code "add a slugify helper"            start with an opening task
+  dsh code -p "what does this repo do?"      answer once and exit
+  dsh code --continue                        reopen the latest session here
+  dsh code --resume session-1234             reopen one session by id
+  dsh code --preset standard                 compose from a different preset
+`);
+}
+/**
+* Resolve the session to reopen from the two mutually exclusive continuation flags.
+* @param program - the parsed command, used to report a usage error.
+* @param options - the flags commander collected.
+* @returns the session id, `'latest'`, or the empty string.
+*/
+function resolveResume(program, options) {
+	if (options.continue === true && options.resume !== void 0) program.error("error: --continue and --resume are mutually exclusive");
+	if (options.continue === true) return "latest";
+	if (options.resume === void 0) return "";
+	if (options.resume.trim() === "") program.error("error: --resume needs a session id");
+	return options.resume;
+}
+/**
+* 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.
+*/
+function apply(ctx) {
+	const program = codingCliCommand();
+	program.action(() => {
+		const options = program.opts();
+		const task = program.args.join(" ").trim();
+		const print = options.print === true;
+		if (print && task === "") program.error("error: --print needs a task, for example: dsh code -p \"run the tests\"");
+		const preset = options.preset ?? "";
+		if (options.preset !== void 0 && preset.trim() === "") program.error("error: --preset needs a preset id");
+		ctx.provide(CODING_CLI_STARTUP_SERVICE, {
+			task,
+			resume: resolveResume(program, options),
+			preset,
+			print
+		});
+	});
+	parseCmdline(ctx, program);
+}
+
+//#endregion
+export { CODING_CLI_STARTUP_SERVICE, apply, inject, name };

package/lib/types/approval.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The terminal's approval answerer: it puts one pending tool call to the
+ * keyboard and returns the decision.
+ *
+ * `ApprovalOutcome` has no remembered grant — the vocabulary is `allowed-once`,
+ * `rejected`, `cancelled`, and `unavailable` — so "allow every call to this
+ * tool" is this surface's own state, kept here and answered as `allowed-once`
+ * without asking again.
+ * @module codsh-bundle/src/approval
+ */
+import type { ApprovalOutcome, ApprovalRequest } from '@deepseek-ai/dsh-user-approval';
+import type { Theme } from './theme.ts';
+/** One keystroke the approval prompt accepts. */
+export type ApprovalAnswer = 'once' | 'always' | 'reject';
+/** Reads one approval keystroke from the terminal. */
+export interface ApprovalPrompt {
+    /**
+     * Ask the person about one pending call.
+     * @param toolName - the tool awaiting a decision.
+     * @param reason - the asker's explanation, when it supplied one.
+     * @param signal - aborts the prompt when the call is cancelled.
+     * @returns the chosen answer, or undefined when the prompt was aborted.
+     */
+    ask(toolName: string, reason: string | undefined, signal: AbortSignal | undefined): Promise<ApprovalAnswer | undefined>;
+}
+/**
+ * Approval state for one terminal session.
+ *
+ * The remembered set is per-process and never written to disk. An
+ * {@link ApprovalRequest} carries the tool name, reason, and call id but NOT
+ * the call arguments, so a grant cannot be narrowed to "this command" — it
+ * covers every later call to that tool. Persisting a grant that broad across
+ * runs would outlive the intent that produced it.
+ */
+export declare class TerminalApproval {
+    private readonly prompt;
+    private readonly theme;
+    private readonly write;
+    private readonly allowed;
+    constructor(prompt: ApprovalPrompt, theme: Theme, write: (line: string) => void);
+    /** Tool names granted for the rest of this process, in grant order. */
+    get remembered(): readonly string[];
+    /** Forget every remembered grant, so the next call of each tool asks again. */
+    clear(): void;
+    /**
+     * Decide one request, asking the keyboard unless the tool is already granted.
+     * @param req - the pending decision.
+     * @returns the outcome for this request.
+     */
+    decide(req: ApprovalRequest): Promise<ApprovalOutcome>;
+}
+/**
+ * Map one keystroke to an approval answer.
+ * @param key - the character typed at the prompt.
+ * @returns the answer, or undefined when the key means nothing here.
+ */
+export declare function answerForKey(key: string): ApprovalAnswer | undefined;

package/lib/types/banner.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The opening banner: what answered, where, and which keys matter.
+ * @module codsh-bundle/src/banner
+ */
+import type { Theme } from './theme.ts';
+/** What the banner reports about the composed session. */
+export interface BannerFacts {
+    /** Model route answering this session. */
+    model: string;
+    /** Composed preset, absent when the deployment composes no roster. */
+    preset?: string | undefined;
+    /** Session workspace. */
+    cwd: string;
+    /** Checked-out branch, absent outside a repository. */
+    branch?: string | undefined;
+    /** Session identity, so a person can resume this exact conversation later. */
+    session: string;
+    /** Whether Escape can reach the surface; decides which interrupt is named. */
+    readsKeys: boolean;
+    /** Whether the transcript replayed a resumed conversation above the banner. */
+    resumed: boolean;
+}
+/**
+ * Render the opening banner.
+ * @param facts - what to report.
+ * @param theme - styling for the frame and the detail lines.
+ * @param columns - display columns available; a narrow terminal loses the frame.
+ * @returns the lines to print, ending with a blank separator.
+ */
+export declare function bannerLines(facts: BannerFacts, theme: Theme, columns: number): string[];

package/lib/types/completion.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Completion sources for the prompt: slash commands, and workspace files behind
+ * an `@` mention.
+ *
+ * Bare prose never completes. A sentence headed for the model would be rewritten
+ * by a completer guessing at it, so a path has to be asked for — `@` is that
+ * request, and it is also what makes the mention legible to the model, which
+ * reads the file with its own tools.
+ *
+ * Matching is fuzzy, not prefix: the person knows a fragment of the name, not
+ * where in the path it starts. A prefix match still ranks first, so the fuzzy
+ * fallback never steals an exact intention.
+ * @module codsh-bundle/src/completion
+ */
+/** One completable command: its name without the slash, and what it does. */
+export interface CompletableCommand {
+    name: string;
+    description: string;
+}
+/** `readline`'s completer result: the candidates, and the substring they replace. */
+export type CompletionResult = [completions: string[], substring: string];
+/**
+ * Score `needle` against `hay` as a fuzzy subsequence.
+ *
+ * Consecutive hits and hits on a boundary (start, or after a separator) score
+ * higher, which is what ranks `src/idx` matches the way a person expects. A
+ * needle that is not a subsequence scores nothing at all.
+ * @param needle - what was typed, matched case-insensitively.
+ * @param hay - the candidate.
+ * @returns the score, or undefined when it does not match.
+ */
+export declare function fuzzyScore(needle: string, hay: string): number | undefined;
+/** Drop the cached workspace walk, so a test controls what the next Tab sees. */
+export declare function resetFileIndex(): void;
+/**
+ * Build the completer for one session.
+ *
+ * The command list is read on each use rather than captured, because a command
+ * registry is scoped and changes with the session's mode — plan mode alone adds
+ * and removes one.
+ * @param commands - reads the currently registered commands.
+ * @param cwd - the workspace `@` mentions resolve against.
+ * @returns a completer over the word under the cursor.
+ */
+export declare function createCompleter(commands: () => readonly CompletableCommand[], cwd: string): (line: string) => CompletionResult;

package/lib/types/console.d.ts

@@ -0,0 +1,240 @@
+/**
+ * The process-facing terminal, in two shapes.
+ *
+ * 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
+ * shapes answer the same reads, which is what keeps piped runs and tests on the
+ * same code path as a person typing.
+ * @module codsh-bundle/src/console
+ */
+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. */
+export interface InputStream extends NodeJS.ReadableStream {
+    readonly isTTY?: boolean;
+    setRawMode?(mode: boolean): unknown;
+}
+/** Where the cursor belongs among a region's rows. */
+export interface RegionCursor {
+    row: number;
+    column: number;
+}
+/** Line input and output over one pair of process streams. */
+export declare class TerminalConsole {
+    private readonly input;
+    private readonly output;
+    private readonly rl;
+    private readonly decoder;
+    private readonly pending;
+    private readonly waiters;
+    private keyHandler;
+    /** Keys decoded before any handler registered — type-ahead is never dropped. */
+    private readonly earlyKeys;
+    private escapeTimer;
+    private ended;
+    /** 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;
+    /**
+     * Whether this surface owns the keyboard.
+     *
+     * That needs both streams on a terminal: raw mode is what delivers a key
+     * before its line, and there is no point managing rows on a stream with no
+     * cursor.
+     */
+    get readsKeys(): boolean;
+    /** Whether input has finished. */
+    get finished(): boolean;
+    /**
+     * Register a handler for terminal window changes.
+     * @param handler - called after each resize while registered.
+     * @returns a disposer that removes it.
+     */
+    onResize(handler: () => void): () => void;
+    /**
+     * 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.
+     *
+     * 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;
+    /**
+     * Route decoded keys to a handler.
+     * @param handler - receives every key while registered.
+     * @returns a disposer that removes it.
+     */
+    onKey(handler: (key: Key) => void): () => void;
+    /**
+     * Decode one read and dispatch its keys.
+     * @param chunk - the bytes the terminal delivered.
+     */
+    private onBytes;
+    /** Hand one key to the handler, or hold it until one registers. */
+    private deliver;
+    /** Wait briefly for the rest of a held sequence, then resolve it as Escape. */
+    private armEscapeFlush;
+    /**
+     * Hand one input line to the longest-waiting read, or queue it.
+     * @param line - the line the reader produced.
+     */
+    private offer;
+    /** Mark input finished and release every waiting read. */
+    private end;
+    /**
+     * Keep one finished transcript line.
+     *
+     * 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 rows pinned below the transcript.
+     *
+     * This is the whole live area: an input box, a completion menu, a working
+     * 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 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;
+    /**
+     * 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.
+     */
+    /**
+     * 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;
+    /**
+     * Set the terminal window title.
+     * @param title - the title text; control bytes are the terminal's to reject.
+     */
+    setTitle(title: string): void;
+    /**
+     * Read one line from a piped stream.
+     *
+     * Only the non-terminal shape reads this way; with the keyboard owned, input
+     * arrives as keys and the caller drives an editor instead.
+     * @param signal - aborts the pending read.
+     * @returns the line, or undefined when input ended or the read aborted.
+     */
+    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/custom-commands.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Custom slash commands from Markdown files.
+ *
+ * A file named `review.md` under a commands root becomes `/review`: its
+ * frontmatter `description` labels it in the completion menu, and its body is
+ * the prompt submitted when the command runs — with `$ARGUMENTS` replaced by
+ * whatever followed the name. They are canned prompts, not handlers: execution
+ * goes through the same submission path as a typed message.
+ * @module codsh-bundle/src/custom-commands
+ */
+/** One loaded command. */
+export interface CustomCommand {
+    /** The name typed after the slash. */
+    name: string;
+    /** Menu label, from frontmatter or a fallback naming the file. */
+    description: string;
+    /** The prompt body, with `$ARGUMENTS` placeholders intact. */
+    template: string;
+}
+/** What loading produced: the commands, and what was skipped and why. */
+export interface CustomCommandLoad {
+    commands: CustomCommand[];
+    /** One line per skipped file, for the surface to show once at startup. */
+    warnings: string[];
+}
+/**
+ * Parse one command file: optional `---` frontmatter with a `description`
+ * line, then the prompt body.
+ * @param source - the file content.
+ * @returns the description (empty when absent) and the body.
+ */
+export declare function parseCommandFile(source: string): {
+    description: string;
+    body: string;
+};
+/**
+ * Fill a template with the typed arguments.
+ * @param template - the prompt body.
+ * @param typed - what followed the command name, possibly empty.
+ * @returns the prompt to submit: placeholders replaced, or the arguments
+ *   appended when the template never asked for them.
+ */
+export declare function expandTemplate(template: string, typed: string): string;
+/**
+ * Load every command under the given roots, later roots shadowing earlier.
+ *
+ * A missing root is normal (most setups define no custom commands); an
+ * unreadable or misnamed file is a warning, never a failed startup — a broken
+ * canned prompt should cost that prompt, not the session.
+ * @param roots - directories to scan, lowest precedence first.
+ * @param taken - names already registered, which a file cannot shadow.
+ * @returns the loaded commands and the warnings to show once.
+ */
+export declare function loadCustomCommands(roots: readonly string[], taken: ReadonlySet<string>): Promise<CustomCommandLoad>;