terminal-pilot 0.0.49 → 0.0.51

package/node_modules/@poe-code/user-error/README.md

@@ -0,0 +1,56 @@
+# @poe-code/user-error
+
+The shared user-error type every workspace package throws for expected user
+mistakes, and the guard the CLI renders them with.
+
+`src/cli/errors.ts` cannot be imported from `packages/*`, so package code used to
+throw a plain `Error` for recoverable conditions. `src/cli/bootstrap.ts` then
+treated each one as a crash: an `Error:` prefix plus a `See logs at
+~/.poe-code/logs/errors.log` pointer to a log that adds nothing for a typo. This
+package gives packages a classification the CLI honours.
+
+## Usage
+
+```ts
+import { UserError, isUserError } from "@poe-code/user-error";
+
+throw new UserError('Unknown agent "clyde". Try: claude, codex, gemini.');
+
+throw new UserError("No API key found.", {
+  hint: "Create one at https://poe.com/api_key",
+  cause: readError
+});
+
+if (isUserError(error)) {
+  // render the message as guidance: no stack trace, no log pointer
+}
+```
+
+Throw a `UserError` when the user can fix the condition themselves, and say how:
+name the value that was rejected and the valid ones, the path that was searched,
+or the URL that issues the key. Keep plain `Error` for genuine failures — those
+should reach the log.
+
+## Public API
+
+- `UserError`: `Error` subclass with `name === "UserError"` and an optional
+  `hint` for the recovery step. Accepts the standard `cause` option.
+- `isUserError(error)`: true for a `UserError` **or** any `Error` whose `name` is
+  `"UserError"`.
+
+## Cross-bundle recognition
+
+`isUserError` matches on `error.name`, not `instanceof`. `toolcraft` publishes its
+own `UserError` (`packages/toolcraft/src/user-error.ts`) as a separately released
+framework, and an instance crossing a bundle boundary fails `instanceof` against
+this package's class. Name matching recognises both, and mirrors the existing
+`isSilentError()` precedent in `src/cli/errors.ts`. toolcraft deliberately does
+not depend on this package — the coupling would run the wrong way.
+
+## Config Options
+
+This package reads no configuration.
+
+## Environment Variables
+
+This package reads no environment variables.

package/node_modules/@poe-code/user-error/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * An expected user mistake: bad input, a missing file, an unknown id, absent
+ * credentials. Thrown where the condition is detected so the CLI can render the
+ * message as guidance instead of dressing it in system-failure chrome.
+ */
+export declare class UserError extends Error {
+    readonly hint?: string;
+    constructor(message: string, options?: ErrorOptions & {
+        hint?: string;
+    });
+}
+/**
+ * Detects user errors by name as well as identity, so an instance created in
+ * another bundle (toolcraft publishes its own `UserError`) is still recognised
+ * where `instanceof` would fail.
+ */
+export declare function isUserError(error: unknown): boolean;

package/node_modules/@poe-code/user-error/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * An expected user mistake: bad input, a missing file, an unknown id, absent
+ * credentials. Thrown where the condition is detected so the CLI can render the
+ * message as guidance instead of dressing it in system-failure chrome.
+ */
+export class UserError extends Error {
+    hint;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "UserError";
+        this.hint = options?.hint;
+    }
+}
+/**
+ * Detects user errors by name as well as identity, so an instance created in
+ * another bundle (toolcraft publishes its own `UserError`) is still recognised
+ * where `instanceof` would fail.
+ */
+export function isUserError(error) {
+    return error instanceof Error && error.name === "UserError";
+}

package/node_modules/@poe-code/user-error/package.json

@@ -0,0 +1,24 @@
+{
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "node ../../scripts/guard-package-dist.mjs && tsc"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/poe-platform/poe-code.git",
+    "directory": "packages/user-error"
+  }
+}

package/node_modules/toolcraft-design/README.md

@@ -83,6 +83,36 @@ import { renderTable } from "toolcraft-design/render-table";
 - Root-level types: `Row`, `DetailItem`, `Detail`, `DetailCtx`, `Action`, `ActionContext`, `ExplorerConfig`, `ReorderContext`, `Tone`.
 - The namespace also exports `createInitialState`, `resolveBindings`, and the remaining explorer event, binding, layout, size, state, and effect types.
 
+Explorers declare one to three list or detail panes. Printable input always filters; actions use optional Ctrl accelerators:
+
+```ts
+await runExplorer({
+  title: "Plans",
+  panes: [
+    { id: "plans", kind: "list", title: "Plans", rows: loadPlans },
+    { id: "preview", kind: "detail", title: "Preview", render: renderPlan }
+  ],
+  actions: [
+    { id: "edit", label: "Edit", accelerator: "e", handler: editPlan },
+    { id: "remove", label: "Remove", destructive: true, handler: removePlan }
+  ]
+});
+```
+
+| Input | Behavior |
+| --- | --- |
+| Printable text / paste | Filter the focused list |
+| Up, Down, PageUp, PageDown, Home, End | Navigate |
+| Ctrl+U, Ctrl+D | Move half a page |
+| Enter | Open the action menu |
+| Ctrl+P | Open the command palette |
+| Tab | Cycle pane focus |
+| Space | Toggle selection |
+| Escape | Dismiss, clear the filter, then quit |
+| Ctrl+C | Quit immediately |
+
+Set `POE_CODE_TUI_TRACE` to a file path to write JSONL input and frame diagnostics. It is unset and disabled by default.
+
 ### Terminal Markdown
 
 - `parse`: parses Markdown into `MdNode` values.

package/node_modules/toolcraft-design/dist/dashboard/terminal-width.d.ts

@@ -2,3 +2,4 @@ export declare function graphemes(value: string): string[];
 export declare function displayWidth(value: string, startColumn?: number): number;
 export declare function expandTabs(value: string, startColumn?: number): string;
 export declare function graphemeWidth(segment: string): number;
+export declare function truncateToWidth(text: string, width: number): string;

package/node_modules/toolcraft-design/dist/dashboard/terminal-width.js

@@ -33,7 +33,24 @@ export function graphemeWidth(segment) {
     if (codePoint === undefined || isZeroWidthCodePoint(codePoint)) {
         return 0;
     }
-    return isWideCodePoint(codePoint) || isFlagSegment(segment) ? 2 : 1;
+    return isWideCodePoint(codePoint) || isFlagSegment(segment) || segment.includes("\ufe0f") ? 2 : 1;
+}
+export function truncateToWidth(text, width) {
+    if (width <= 0)
+        return "";
+    if (displayWidth(text) <= width)
+        return text;
+    const target = Math.max(0, width - 1);
+    let result = "";
+    let used = 0;
+    for (const segment of graphemes(text)) {
+        const segmentWidth = graphemeWidth(segment);
+        if (used + segmentWidth > target)
+            break;
+        result += segment;
+        used += segmentWidth;
+    }
+    return `${result}…`;
 }
 function isZeroWidthCodePoint(codePoint) {
     return (codePoint >= 0x0300 && codePoint <= 0x036f)

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

@@ -1,6 +1,6 @@
 import type { ExplorerEvent } from "./events.js";
 import type { Action, ActionContext, ExplorerState, Row, Tone } from "./state.js";
-export type ActionSource = "row" | "detail";
+export type ActionSource = "row" | "detail" | "both";
 type ExplorerKeypressEvent = Extract<ExplorerEvent, {
     type: "key";
 }>["key"];
@@ -13,7 +13,8 @@ export type ActionRuntimeHandles = {
         content: string;
     }) => void;
     toast: (msg: string, tone?: Tone) => void;
-    confirm: (prompt: string) => Promise<boolean>;
+    confirm: ActionContext<unknown>["confirm"];
+    promptText: ActionContext<unknown>["promptText"];
     exit: (after?: () => void | Promise<void>) => void;
 };
 export declare function resolveAction<R>(state: ExplorerState, keyEvent: ExplorerKeypressEvent): Action<R> | null;

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

@@ -12,11 +12,14 @@ export function resolveAction(state, keyEvent) {
     return actionState.action;
 }
 export function buildActionContext(state, _action, source, runtimeHandles, rowsOverride) {
-    const row = rowsOverride?.[0] ?? currentRow(state) ?? { id: "", title: "" };
+    const detailActive = source === "both" && state.focused === "detail";
+    const row = rowsOverride?.[0] ??
+        (detailActive ? currentDetailRow(state) : currentRow(state)) ?? { id: "", title: "" };
+    const panes = runtimePanes(state);
     return {
         row,
         rows: rowsOverride ?? selectedRows(state, row),
-        item: source === "detail" ? currentDetailItem(state) : undefined,
+        item: source === "detail" || detailActive ? currentDetailItem(state) : undefined,
         filter: state.filter,
         refresh: runtimeHandles.refresh,
         reloadDetail: runtimeHandles.reloadDetail,
@@ -24,7 +27,10 @@ export function buildActionContext(state, _action, source, runtimeHandles, rowsO
         openModal: runtimeHandles.openModal,
         toast: runtimeHandles.toast,
         confirm: runtimeHandles.confirm,
-        exit: runtimeHandles.exit
+        promptText: runtimeHandles.promptText,
+        exit: runtimeHandles.exit,
+        activePane: state.focused === "detail" ? panes[1] : panes[0],
+        inactivePane: state.focused === "detail" ? panes[0] : panes[1]
     };
 }
 function currentRow(state) {
@@ -33,9 +39,49 @@ function currentRow(state) {
 function currentDetailItem(state) {
     return state.detail.items?.[state.detail.cursor];
 }
+function currentDetailRow(state) {
+    const item = currentDetailItem(state);
+    return item === undefined
+        ? undefined
+        : { id: item.id, title: item.title ?? item.id, subtitle: item.subtitle, badge: item.badge };
+}
 function selectedRows(state, fallback) {
     if (!state.multiSelect || state.selected.size === 0) {
         return fallback.id === "" ? [] : [fallback];
     }
-    return state.rows.filter((row) => state.selected.has(row.id));
+    const source = state.focused === "detail"
+        ? (state.detail.items ?? []).map((item) => ({
+            id: item.id,
+            title: item.title ?? item.id,
+            subtitle: item.subtitle,
+            badge: item.badge
+        }))
+        : state.rows;
+    return source.filter((row) => state.selected.has(row.id));
+}
+function runtimePanes(state) {
+    const definitions = state.paneDefinitions;
+    return [
+        {
+            id: definitions[0]?.id ?? "list",
+            title: definitions[0]?.title ?? state.title,
+            rows: state.rows,
+            cursor: state.cursor,
+            selected: state.selected,
+            filter: state.filter
+        },
+        {
+            id: definitions[1]?.id ?? "detail",
+            title: definitions[1]?.title ?? "Preview",
+            rows: (state.detail.items ?? []).map((item) => ({
+                id: item.id,
+                title: item.title ?? item.id,
+                subtitle: item.subtitle,
+                badge: item.badge
+            })),
+            cursor: state.detail.cursor,
+            selected: state.selected,
+            filter: ""
+        }
+    ];
 }

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

@@ -65,7 +65,12 @@ export type ExplorerEvent = {
 };
 export type ConfirmModal = {
     kind: "confirm";
-    action: Action<unknown>;
-    rows: Row[];
+    title: string;
+    message: string;
+    confirmLabel: string;
+    cancelLabel: string;
+    destructive: boolean;
+    action?: Action<unknown>;
+    rows?: Row[];
     resolver: (ok: boolean) => void;
 };

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

@@ -3,7 +3,7 @@ const CONSECUTIVE_BONUS = 14;
 const WORD_START_BONUS = 10;
 const EARLY_MATCH_BONUS = 3;
 export function filterRows(query, rows, opts = {}) {
-    if (query.length === 0) {
+    if (query.trim().length === 0) {
         return rows.map((_, index) => ({ index, score: 0, positions: [] }));
     }
     const preparedQuery = opts.caseSensitive === true ? query : query.toLocaleLowerCase();

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

@@ -1,10 +1,8 @@
 import type { Detail, DetailCtx, Row } from "./state.js";
 export { runExplorer } from "./runtime.js";
-export { runTwoPaneExplorer, renderTwoPaneExplorer, TwoPaneExplorerRuntime } from "./two-pane.js";
-export { createInitialState } from "./state.js";
+export { createInitialState, normalizeExplorerConfig } from "./state.js";
 export { resolveBindings } from "./keymap.js";
 export type { Effect, ExplorerEvent } from "./events.js";
 export type { BindingTarget, ExplorerBindingDefaults, ExplorerBuiltinCommand, ResolvedBindings } from "./keymap.js";
-export type { Action, ActionContext, Detail, DetailCtx, DetailItem, Dirty, ExplorerConfig, ExplorerLayoutMode, ExplorerSize, ExplorerState, ReorderContext, Row, Tone } from "./state.js";
-export type { TwoPaneAction, TwoPaneActionContext, TwoPaneDefinition, TwoPaneExplorerConfig, TwoPaneExplorerState, TwoPanePaneState, TwoPaneRow } from "./two-pane.js";
+export type { Action, ActionContext, ConfirmPromptOptions, Detail, DetailCtx, DetailItem, Dirty, ExplorerConfig, PaneConfig, ListPaneConfig, DetailPaneConfig, PaneRuntimeState, ExplorerLayoutMode, ExplorerSize, ExplorerState, ReorderContext, Row, Tone } from "./state.js";
 export declare function singleDetail<R>(fn: (row: Row, ctx: DetailCtx) => string | Promise<string>): Detail<R>;

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

@@ -1,6 +1,5 @@
 export { runExplorer } from "./runtime.js";
-export { runTwoPaneExplorer, renderTwoPaneExplorer, TwoPaneExplorerRuntime } from "./two-pane.js";
-export { createInitialState } from "./state.js";
+export { createInitialState, normalizeExplorerConfig } from "./state.js";
 export { resolveBindings } from "./keymap.js";
 export function singleDetail(fn) {
     return {

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

@@ -1,8 +1,8 @@
 import type { ExplorerEvent } from "./events.js";
 import type { DetailCtx, DetailItem } from "./state.js";
 export declare const LOADING_INDICATOR_MS = 150;
-export declare const DETAIL_DEBOUNCE_MS = 100;
+export declare const DETAIL_DEBOUNCE_MS = 30;
 export declare function createDetailJobs(emit: (event: ExplorerEvent) => void): {
-    schedule: (rowId: string, items: (ctx: DetailCtx) => Promise<DetailItem[]>, ctx: DetailCtx) => Promise<void>;
+    schedule: (rowId: string, token: number, items: (ctx: DetailCtx) => Promise<DetailItem[]>, ctx: DetailCtx) => Promise<void>;
     abort: () => void;
 };

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

@@ -1,12 +1,11 @@
 export const LOADING_INDICATOR_MS = 150;
-export const DETAIL_DEBOUNCE_MS = 100;
+export const DETAIL_DEBOUNCE_MS = 30;
 export function createDetailJobs(emit) {
-    let token = 0;
     let lastScheduleAt = 0;
     let current = null;
     const abortedTokens = new Set();
     return {
-        async schedule(rowId, items, ctx) {
+        async schedule(rowId, nextToken, items, ctx) {
             if (current !== null) {
                 current.controller.abort();
                 clearTimeout(current.loadingTimer);
@@ -14,7 +13,6 @@ export function createDetailJobs(emit) {
             const scheduledAt = Date.now();
             const debounce = scheduledAt - lastScheduleAt < DETAIL_DEBOUNCE_MS;
             lastScheduleAt = scheduledAt;
-            const nextToken = ++token;
             const controller = new AbortController();
             let finished = false;
             const loadingTimer = setTimeout(() => {
@@ -26,7 +24,7 @@ export function createDetailJobs(emit) {
             try {
                 if (debounce) {
                     await waitUnlessAborted(DETAIL_DEBOUNCE_MS, controller.signal);
-                    if (controller.signal.aborted || nextToken !== token) {
+                    if (controller.signal.aborted || current?.token !== nextToken) {
                         return;
                     }
                 }

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

@@ -1,6 +1,6 @@
 import type { ExplorerEvent } from "./events.js";
 import type { ExplorerConfig } from "./state.js";
-export type ExplorerBuiltinCommand = "quit" | "filter" | "help" | "palette" | "cursorUp" | "cursorDown" | "top" | "bottom" | "pageUp" | "pageDown" | "focusNext" | "escape" | "confirm" | "toggleSelect" | "selectAll" | "clearSelection" | "detailScrollDown" | "detailScrollUp" | "extendSelectionUp" | "extendSelectionDown" | "reorderUp" | "reorderDown";
+export type ExplorerBuiltinCommand = "quit" | "filter" | "help" | "palette" | "cursorUp" | "cursorDown" | "top" | "bottom" | "pageUp" | "pageDown" | "focusNext" | "escape" | "confirm" | "halfPageUp" | "halfPageDown" | "toggleSelect" | "selectAll" | "clearSelection" | "detailScrollDown" | "detailScrollUp" | "extendSelectionUp" | "extendSelectionDown" | "reorderUp" | "reorderDown";
 export type BindingTarget = {
     type: "builtin";
     id: ExplorerBuiltinCommand;
@@ -8,14 +8,24 @@ export type BindingTarget = {
     type: "action";
     id: string;
 };
-type ExplorerKeypressEvent = Extract<ExplorerEvent, {
+type Key = Extract<ExplorerEvent, {
     type: "key";
 }>["key"];
 export interface ResolvedBindings {
     bindings: ReadonlyMap<string, BindingTarget>;
     keysByTarget: ReadonlyMap<string, readonly string[]>;
-    resolve: (event: ExplorerKeypressEvent) => BindingTarget | undefined;
+    resolve: (event: Key) => BindingTarget | undefined;
 }
 export type ExplorerBindingDefaults = Partial<Record<ExplorerBuiltinCommand, string[]>>;
+export interface HelpSection {
+    title: string;
+    entries: Array<{
+        key: string;
+        label: string;
+    }>;
+}
 export declare function resolveBindings<R>(config: ExplorerConfig<R>, defaults?: ExplorerBindingDefaults): ResolvedBindings;
+export declare function assertNoBareLetterBindings<R>(config: ExplorerConfig<R>): void;
+export declare function assertAcceleratorsFree<R>(config: ExplorerConfig<R>): void;
+export declare function keymapToHelp<R>(config: ExplorerConfig<R>): HelpSection[];
 export {};