terminal-pilot 0.0.30 → 0.0.32

package/node_modules/toolcraft-design/dist/explorer/render/test-fixtures.js

@@ -0,0 +1,156 @@
+import { ScreenBuffer, cellToAnsi } from "../../dashboard/buffer.js";
+import { filterRows } from "../filter.js";
+import { computeExplorerLayout } from "../layout.js";
+import { createInitialState, REGION_ALL } from "../state.js";
+import { renderExplorer } from "./index.js";
+export function renderStateSnapshot(state) {
+    const screen = new ScreenBuffer(state.size.cols, state.size.rows);
+    renderExplorer(state, screen);
+    return dumpScreen(screen);
+}
+export function dumpScreen(screen) {
+    const lines = [];
+    for (let y = 0; y < screen.height; y += 1) {
+        let line = "";
+        for (let x = 0; x < screen.width; x += 1) {
+            line += cellToAnsi(screen.get(x, y));
+        }
+        lines.push(line);
+    }
+    return lines.join("\n");
+}
+export function fixtureState(overrides = {}) {
+    const rows = overrides.rows ?? fixtureRows();
+    const filter = overrides.filter ?? "";
+    const size = overrides.size ?? { cols: 100, rows: 14 };
+    const config = {
+        title: overrides.title ?? "Plans",
+        rows: async () => rows,
+        detail: {
+            items: async () => []
+        },
+        actions: fixtureActions(),
+        multiSelect: true,
+        emptyHint: "No plans"
+    };
+    const state = createInitialState(config, size);
+    state.rows = rows;
+    state.filter = filter;
+    const matches = filterRows(filter, rows);
+    state.filtered = matches.map((match) => match.index);
+    state.matchPositions = new Map(matches.map((match) => [match.index, match.positions]));
+    state.cursor = overrides.cursor ?? 0;
+    state.detail = overrides.detail ?? {
+        rowId: rows[0]?.id ?? null,
+        items: [singleDetailItem()],
+        cursor: 0,
+        scroll: 0,
+        token: 1,
+        loading: false
+    };
+    state.selected = overrides.selected ?? new Set(["27", "24"]);
+    state.focused = overrides.focused ?? "list";
+    state.modal = overrides.modal ?? null;
+    state.toast = overrides.toast ?? null;
+    state.dirty = overrides.dirty ?? REGION_ALL;
+    state.layout = computeExplorerLayout(size).mode;
+    for (const [key, value] of Object.entries(overrides)) {
+        state[key] = value;
+    }
+    return state;
+}
+export function fixtureRows() {
+    return [
+        {
+            id: "27",
+            title: "Explorer TUI library",
+            subtitle: "2d · kjopek · design-system",
+            badge: { text: "active", tone: "success" },
+            group: "Current"
+        },
+        {
+            id: "26",
+            title: "ACP telemetry converters",
+            subtitle: "3d · kjopek · acp",
+            badge: { text: "draft", tone: "warning" },
+            group: "Current"
+        },
+        {
+            id: "25",
+            title: "Maestro",
+            subtitle: "5d · kjopek · pipeline",
+            group: "Backlog"
+        },
+        {
+            id: "24",
+            title: "Tasks board sync",
+            subtitle: "1w · kjopek · superintendent",
+            badge: { text: "blocked", tone: "error" },
+            group: "Backlog"
+        }
+    ];
+}
+export function singleDetailItem() {
+    return {
+        id: "body",
+        render: () => [
+            "# Explorer TUI library",
+            "",
+            "A reusable list + detail + actions explorer component.",
+            "",
+            "## What we're building",
+            "A generic three-region explorer TUI."
+        ].join("\n")
+    };
+}
+export function listDetailItems() {
+    return [
+        {
+            id: "thread-1",
+            title: "packages/auth/src/refresh.ts:42",
+            subtitle: "kjopek · requested changes",
+            badge: { text: "fix", tone: "error" },
+            render: () => "The lock is released before the await."
+        },
+        {
+            id: "thread-2",
+            title: "packages/auth/src/refresh.ts:88",
+            subtitle: "nit",
+            badge: { text: "nit", tone: "info" },
+            render: () => "Rename `t` to `token` for readability."
+        }
+    ];
+}
+function fixtureActions() {
+    return [
+        {
+            id: "edit",
+            label: "edit",
+            key: "e",
+            handler: () => undefined,
+            showInFooter: true
+        },
+        {
+            id: "archive",
+            label: "archive",
+            key: "a",
+            handler: () => undefined,
+            showInFooter: true
+        },
+        {
+            id: "delete",
+            label: "delete",
+            key: "d",
+            handler: () => undefined,
+            destructive: true,
+            showInFooter: true
+        },
+        {
+            id: "open",
+            label: "open",
+            handler: () => undefined,
+            primary: true,
+            showInFooter: true
+        }
+    ];
+}

package/node_modules/toolcraft-design/dist/explorer/render/text.d.ts

@@ -0,0 +1,12 @@
+export interface GraphemeCell {
+    value: string;
+    start: number;
+    end: number;
+    width: number;
+}
+export declare function cellWidth(value: string, startColumn?: number): number;
+export declare function fitToWidth(text: string, width: number, startColumn?: number): string;
+export declare function centerCells(text: string, width: number, startColumn?: number): string;
+export declare function padEndCells(text: string, width: number, fill?: string, startColumn?: number): string;
+export declare function splitGraphemeCells(value: string, startColumn?: number): GraphemeCell[];
+export declare function stripAnsi(value: string): string;

package/node_modules/toolcraft-design/dist/explorer/render/text.js

@@ -0,0 +1,81 @@
+import { displayWidth, graphemes } from "../../dashboard/terminal-width.js";
+const ELLIPSIS = "…";
+export function cellWidth(value, startColumn = 0) {
+    return displayWidth(value, startColumn);
+}
+export function fitToWidth(text, width, startColumn = 0) {
+    if (width <= 0) {
+        return "";
+    }
+    if (cellWidth(text, startColumn) <= width) {
+        return text;
+    }
+    const ellipsisWidth = cellWidth(ELLIPSIS, startColumn);
+    if (ellipsisWidth > width) {
+        return takeCells(text, width, startColumn);
+    }
+    const prefix = takeCells(text, width - ellipsisWidth, startColumn);
+    return `${prefix}${ELLIPSIS}`;
+}
+export function centerCells(text, width, startColumn = 0) {
+    const fitted = fitToWidth(text, width, startColumn);
+    const padding = Math.max(0, Math.floor((width - cellWidth(fitted, startColumn)) / 2));
+    return `${" ".repeat(padding)}${fitted}`;
+}
+export function padEndCells(text, width, fill = " ", startColumn = 0) {
+    let output = takeCells(text, width, startColumn);
+    let used = cellWidth(output, startColumn);
+    let column = startColumn + used;
+    while (used < width) {
+        const fillWidth = cellWidth(fill, column);
+        if (fill.length === 0 || fillWidth <= 0 || used + fillWidth > width) {
+            const spaces = width - used;
+            output += " ".repeat(spaces);
+            used += spaces;
+            column += spaces;
+            continue;
+        }
+        output += fill;
+        used += fillWidth;
+        column += fillWidth;
+    }
+    return output;
+}
+export function splitGraphemeCells(value, startColumn = 0) {
+    const cells = [];
+    let offset = 0;
+    let column = startColumn;
+    for (const segment of graphemes(value)) {
+        const width = cellWidth(segment, column);
+        cells.push({
+            value: segment,
+            start: offset,
+            end: offset + segment.length,
+            width
+        });
+        offset += segment.length;
+        column += width;
+    }
+    return cells;
+}
+export function stripAnsi(value) {
+    return value.replace(/\u001b\[[0-9;]*m/g, "");
+}
+function takeCells(text, width, startColumn) {
+    if (width <= 0) {
+        return "";
+    }
+    let output = "";
+    let used = 0;
+    let column = startColumn;
+    for (const segment of graphemes(text)) {
+        const segmentWidth = cellWidth(segment, column);
+        if (used + segmentWidth > width) {
+            break;
+        }
+        output += segment;
+        used += segmentWidth;
+        column += segmentWidth;
+    }
+    return output;
+}

package/node_modules/toolcraft-design/dist/explorer/runtime.d.ts

@@ -0,0 +1,2 @@
+import { type ExplorerConfig } from "./state.js";
+export declare function runExplorer<R = void>(config: ExplorerConfig<R>): Promise<R | null>;

package/node_modules/toolcraft-design/dist/explorer/runtime.js

@@ -0,0 +1,340 @@
+import { ScreenBuffer, cellToAnsi, diff } from "../dashboard/buffer.js";
+import { createTerminalDriver } from "../dashboard/terminal.js";
+import { createDetailJobs } from "./jobs.js";
+import { computeExplorerLayout } from "./layout.js";
+import { renderExplorer } from "./render/index.js";
+import { step } from "./reducer.js";
+import { createInitialState, REGION_ALL, REGION_MODAL, REGION_TOAST } from "./state.js";
+const TOAST_MS = 2500;
+export async function runExplorer(config) {
+    if (process.stdout.isTTY !== true) {
+        throw new Error("explorer requires a TTY");
+    }
+    const driver = createTerminalDriver();
+    const runtime = new ExplorerRuntime(config, driver);
+    return runtime.run();
+}
+class ExplorerRuntime {
+    config;
+    driver;
+    state;
+    previousBuffer = new ScreenBuffer(0, 0);
+    detailJobs;
+    runtimeHandles;
+    pendingEffects = new Set();
+    unsubscribeKeypress;
+    unsubscribeResize;
+    toastTimer;
+    rowsRequestToken = 0;
+    reorderToken = 0;
+    stopped = false;
+    settle;
+    constructor(config, driver) {
+        this.config = config;
+        this.driver = driver;
+        this.state = createInitialState(config, driver.getSize());
+        this.detailJobs = createDetailJobs((event) => {
+            if (event.type === "detailLoaded") {
+                this.loadDetailContent(event.rowId, event.token, event.items);
+                return;
+            }
+            this.dispatch(event);
+        });
+        this.runtimeHandles = {
+            refresh: async () => {
+                await this.refreshRowsFromSource();
+            },
+            suspendAnd: async (fn) => this.suspendAnd(fn),
+            toast: (msg, tone) => {
+                this.showToast(msg, tone);
+            },
+            confirm: async (prompt) => this.confirm(prompt),
+            exit: (after) => {
+                this.exit(null, after);
+            }
+        };
+    }
+    run() {
+        return new Promise((resolve, reject) => {
+            this.settle = { resolve, reject };
+            try {
+                this.startTerminal();
+                this.render();
+                this.loadRows().catch((error) => {
+                    this.fail(error);
+                });
+            }
+            catch (error) {
+                this.fail(error);
+            }
+        });
+    }
+    startTerminal() {
+        this.driver.enterRawMode();
+        this.driver.enterAltScreen();
+        this.driver.disableLineWrap();
+        this.driver.hideCursor();
+        this.unsubscribeKeypress = this.driver.onKeypress((key) => {
+            this.dispatch({ type: "key", key });
+        });
+        this.unsubscribeResize = this.driver.onResize(() => {
+            const size = this.driver.getSize();
+            this.dispatch({ type: "resize", cols: size.cols, rows: size.rows });
+        });
+    }
+    async loadRows(requestToken = ++this.rowsRequestToken) {
+        const rows = await this.config.rows();
+        if (requestToken === this.rowsRequestToken) {
+            this.dispatch({ type: "rowsLoaded", rows });
+        }
+    }
+    async refreshRowsFromSource() {
+        const requestToken = ++this.rowsRequestToken;
+        await this.config.refresh?.();
+        await this.loadRows(requestToken);
+    }
+    dispatch(event) {
+        if (this.stopped) {
+            return;
+        }
+        const previousState = this.state;
+        const next = step(this.state, event, this.runtimeHandles);
+        this.state = next.state;
+        this.render();
+        this.applyEffects(next.effects, previousState);
+    }
+    applyEffects(effects, previousState) {
+        for (const effect of effects) {
+            if (effect.type === "renderDetail") {
+                this.renderDetail(effect.rowId);
+                continue;
+            }
+            if (effect.type === "persistOrder") {
+                this.track(this.persistOrder(effect.orderedIds, previousState.rows, ++this.reorderToken));
+                continue;
+            }
+            if (effect.type === "suspend") {
+                this.track(this.runActionEffect(effect));
+                continue;
+            }
+            if (effect.type === "exit") {
+                this.exit(effect.result, effect.after);
+            }
+        }
+    }
+    renderDetail(rowId) {
+        const row = this.state.rows.find((candidate) => candidate.id === rowId);
+        if (row === undefined) {
+            return;
+        }
+        const layout = computeExplorerLayout({
+            cols: this.state.size.cols,
+            rows: this.state.size.rows,
+            detailHidden: this.state.layout === "narrow-list-only" || this.state.layout === "too-narrow"
+        });
+        void this.detailJobs.schedule(rowId, (ctx) => this.config.detail.items(row, ctx), {
+            width: layout.detail.width,
+            height: layout.detail.height,
+            row,
+            signal: new AbortController().signal
+        });
+    }
+    loadDetailContent(rowId, token, items) {
+        const row = this.state.rows.find((candidate) => candidate.id === rowId);
+        if (row === undefined) {
+            return;
+        }
+        const layout = computeExplorerLayout({
+            cols: this.state.size.cols,
+            rows: this.state.size.rows,
+            detailHidden: this.state.layout === "narrow-list-only" || this.state.layout === "too-narrow"
+        });
+        const context = {
+            width: layout.detail.width,
+            height: layout.detail.height,
+            row,
+            signal: new AbortController().signal
+        };
+        const preparedItems = items.map((item, itemIndex) => {
+            try {
+                const content = item.render(context);
+                if (typeof content === "string") {
+                    return { ...item, renderedContent: content };
+                }
+                this.track(content.then((resolved) => this.dispatch({ type: "detailItemRendered", rowId, token, itemIndex, content: resolved }), (error) => this.dispatch({
+                    type: "detailItemRendered",
+                    rowId,
+                    token,
+                    itemIndex,
+                    content: error instanceof Error ? `Error: ${error.message}` : "Error: detail failed"
+                })));
+                return { ...item, renderedContent: "Loading detail..." };
+            }
+            catch (error) {
+                return {
+                    ...item,
+                    renderedContent: error instanceof Error ? `Error: ${error.message}` : "Error: detail failed"
+                };
+            }
+        });
+        this.dispatch({ type: "detailLoaded", rowId, token, items: preparedItems });
+    }
+    async persistOrder(orderedIds, previousRows, token) {
+        try {
+            await this.config.reorder?.onReorder(orderedIds, {
+                refresh: this.runtimeHandles.refresh,
+                toast: this.runtimeHandles.toast
+            });
+        }
+        catch (error) {
+            this.showToast(error instanceof Error ? error.message : "Could not persist order", "error");
+            if (token === this.reorderToken) {
+                this.dispatch({ type: "rowsLoaded", rows: previousRows });
+            }
+        }
+    }
+    async runActionEffect(effect) {
+        try {
+            const value = await effect.fn();
+            this.dispatch(effect.resumeWith(value));
+        }
+        catch (error) {
+            this.showToast(error instanceof Error ? error.message : "Action failed", "error");
+            this.dispatch(effect.resumeWith(error));
+        }
+    }
+    async suspendAnd(fn) {
+        this.driver.exitAltScreen();
+        this.driver.enableLineWrap();
+        this.driver.showCursor();
+        this.driver.exitRawMode();
+        try {
+            return await fn();
+        }
+        finally {
+            if (!this.stopped) {
+                this.driver.enterRawMode();
+                this.driver.enterAltScreen();
+                this.driver.disableLineWrap();
+                this.driver.hideCursor();
+                const size = this.driver.getSize();
+                this.dispatch({
+                    type: "suspendResumed",
+                    value: null,
+                    emit: { type: "resize", cols: size.cols, rows: size.rows }
+                });
+            }
+        }
+    }
+    confirm(prompt) {
+        return new Promise((resolve) => {
+            const action = {
+                id: "__confirm__",
+                label: prompt,
+                handler: () => undefined
+            };
+            const row = this.currentRow();
+            this.state = {
+                ...this.state,
+                modal: {
+                    kind: "confirm",
+                    action,
+                    rows: row === undefined ? [] : [row],
+                    resolver: resolve
+                },
+                dirty: REGION_MODAL
+            };
+            this.render();
+        });
+    }
+    showToast(message, tone = "info") {
+        if (this.stopped) {
+            return;
+        }
+        if (this.toastTimer !== undefined) {
+            clearTimeout(this.toastTimer);
+        }
+        this.state = {
+            ...this.state,
+            toast: { message, tone, expiresAt: Date.now() + TOAST_MS },
+            dirty: REGION_TOAST
+        };
+        this.render();
+        this.toastTimer = setTimeout(() => {
+            this.dispatch({ type: "toastExpired" });
+        }, TOAST_MS);
+    }
+    currentRow() {
+        return this.state.rows[this.state.filtered[this.state.cursor] ?? -1];
+    }
+    render() {
+        if (this.stopped) {
+            return;
+        }
+        const size = this.driver.getSize();
+        if (size.cols !== this.state.size.cols || size.rows !== this.state.size.rows) {
+            this.state = step(this.state, { type: "resize", cols: size.cols, rows: size.rows }, this.runtimeHandles).state;
+        }
+        const nextBuffer = this.state.dirty === REGION_ALL
+            ? new ScreenBuffer(this.state.size.cols, this.state.size.rows)
+            : cloneBuffer(this.previousBuffer);
+        renderExplorer(this.state, nextBuffer);
+        this.driver.write(changesToAnsi(diff(this.previousBuffer, nextBuffer)));
+        this.previousBuffer = nextBuffer;
+        this.state = { ...this.state, dirty: 0 };
+    }
+    track(promise) {
+        this.pendingEffects.add(promise);
+        promise.finally(() => {
+            this.pendingEffects.delete(promise);
+        });
+    }
+    exit(result, after) {
+        if (this.stopped) {
+            return;
+        }
+        this.stopped = true;
+        this.unsubscribeKeypress?.();
+        this.unsubscribeResize?.();
+        this.detailJobs.abort();
+        if (this.toastTimer !== undefined) {
+            clearTimeout(this.toastTimer);
+        }
+        this.driver.destroy();
+        Promise.resolve()
+            .then(() => after?.())
+            .then(() => {
+            this.settle?.resolve(result);
+        })
+            .catch((error) => {
+            this.settle?.reject(error);
+        });
+    }
+    fail(error) {
+        if (!this.stopped) {
+            this.stopped = true;
+            this.driver.destroy();
+        }
+        this.settle?.reject(error);
+    }
+}
+function cloneBuffer(buffer) {
+    const next = new ScreenBuffer(buffer.width, buffer.height);
+    for (let y = 0; y < buffer.height; y += 1) {
+        for (let x = 0; x < buffer.width; x += 1) {
+            const cell = buffer.get(x, y);
+            next.put(x, y, cell.ch, cell.style);
+        }
+    }
+    return next;
+}
+function changesToAnsi(changes) {
+    let output = "";
+    for (const change of changes) {
+        output += `${cursorPositionAnsi(change.x, change.y)}${cellToAnsi(change.cell)}`;
+    }
+    return output;
+}
+function cursorPositionAnsi(x, y) {
+    return `\u001b[${Math.max(1, y + 1)};${Math.max(1, x + 1)}H`;
+}

package/node_modules/toolcraft-design/dist/explorer/runtime.test-helpers.d.ts

@@ -0,0 +1,50 @@
+import type { Cell } from "../dashboard/types.js";
+import type { KeypressEvent, TerminalDriver } from "../dashboard/terminal.js";
+export declare class FakeTerminalDriver implements TerminalDriver {
+    private cols;
+    private rows;
+    readonly keyQueue: KeypressEvent[];
+    readonly writes: string[];
+    readonly flushes: Array<Array<{
+        x: number;
+        y: number;
+        cell: Cell;
+    }>>;
+    rawMode: boolean;
+    altScreen: boolean;
+    lineWrap: boolean;
+    cursorVisible: boolean;
+    destroyed: boolean;
+    enterAltScreenCount: number;
+    exitAltScreenCount: number;
+    enterRawModeCount: number;
+    exitRawModeCount: number;
+    private readonly keypressHandlers;
+    private readonly resizeHandlers;
+    constructor(cols?: number, rows?: number);
+    get output(): string;
+    enterRawMode(): void;
+    exitRawMode(): void;
+    enterAltScreen(): void;
+    exitAltScreen(): void;
+    disableLineWrap(): void;
+    enableLineWrap(): void;
+    hideCursor(): void;
+    showCursor(): void;
+    moveTo(x: number, y: number): void;
+    write(text: string): void;
+    flush(changes: Array<{
+        x: number;
+        y: number;
+        cell: Cell;
+    }>): void;
+    getSize(): {
+        cols: number;
+        rows: number;
+    };
+    resize(cols: number, rows: number): void;
+    onResize(handler: () => void): () => void;
+    onKeypress(handler: (key: KeypressEvent) => void): () => void;
+    press(key: KeypressEvent): void;
+    destroy(): void;
+}