byterover-cli 3.9.0 → 3.10.0

package/node_modules/ink-scroll-list/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ByteLand Technology Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/ink-scroll-list/README.md

@@ -0,0 +1,241 @@
+# ink-scroll-list
+
+A high-level ScrollList component for [Ink](https://github.com/vadimdemedes/ink) CLI applications, built on top of [ink-scroll-view](https://github.com/BytelandTechnology/ink-scroll-view).
+
+![License](https://img.shields.io/npm/l/ink-scroll-list)
+![Version](https://img.shields.io/npm/v/ink-scroll-list)
+
+📖 **[Documentation Website](https://ink-scroll-list.byteland.app)**
+
+## ✨ Features
+
+- **Controlled Selection**: Selection state is managed by the parent via `selectedIndex` prop.
+- **Auto-Scrolling**: Automatically scrolls to ensure the selected item is visible.
+- **Flexible Alignment**: Control how the selected item aligns in the viewport (`auto`, `top`, `bottom`, `center`).
+- **Performance**: Optimized to track selection position efficiently without full re-layouts.
+- **Responsive**: Maintains selection visibility when viewport or content changes.
+
+## 🎬 Demos
+
+### Selection & Navigation
+
+![Selection Demo](docs/_media/selection.svg)
+
+### Scroll Alignment Modes
+
+![Alignment Demo](docs/_media/alignment.svg)
+
+### Expand/Collapse
+
+![Expand Demo](docs/_media/expand.svg)
+
+### Dynamic Items
+
+![Dynamic Demo](docs/_media/dynamic.svg)
+
+## 📦 Installation
+
+```bash
+npm install ink-scroll-list
+# Peer dependencies
+npm install ink react
+```
+
+## 🚀 Usage
+
+`ScrollList` is a **controlled component** - the parent component owns and manages the selection state via the `selectedIndex` prop.
+
+```tsx
+import React, { useRef, useState } from "react";
+import { render, Text, Box, useInput } from "ink";
+import { ScrollList, ScrollListRef } from "ink-scroll-list";
+
+const App = () => {
+  const listRef = useRef<ScrollListRef>(null);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const items = Array.from({ length: 20 }).map((_, i) => `Item ${i + 1}`);
+
+  // Handle keyboard navigation in the parent
+  useInput((input, key) => {
+    if (key.upArrow) {
+      setSelectedIndex((prev) => Math.max(prev - 1, 0));
+    }
+    if (key.downArrow) {
+      setSelectedIndex((prev) => Math.min(prev + 1, items.length - 1));
+    }
+    if (input === "g") {
+      setSelectedIndex(0); // Jump to first
+    }
+    if (input === "G") {
+      setSelectedIndex(items.length - 1); // Jump to last
+    }
+    if (key.return) {
+      console.log(`Selected: ${items[selectedIndex]}`);
+    }
+  });
+
+  return (
+    <Box borderStyle="single" height={10}>
+      <ScrollList ref={listRef} selectedIndex={selectedIndex}>
+        {items.map((item, i) => (
+          <Box key={i}>
+            <Text color={i === selectedIndex ? "green" : "white"}>
+              {i === selectedIndex ? "> " : "  "}
+              {item}
+            </Text>
+          </Box>
+        ))}
+      </ScrollList>
+    </Box>
+  );
+};
+
+render(<App />);
+```
+
+## 📚 API Reference
+
+For detailed API documentation, see [API Reference](docs/api/README.md).
+
+### Props (`ScrollListProps`)
+
+Extends `ScrollViewProps` from `ink-scroll-view`.
+
+| Prop              | Type                                      | Description                                          |
+| :---------------- | :---------------------------------------- | :--------------------------------------------------- |
+| `selectedIndex`   | `number`                                  | The currently selected item index (controlled).      |
+| `scrollAlignment` | `'auto' \| 'top' \| 'bottom' \| 'center'` | Alignment mode for selected item. Default: `'auto'`. |
+| ...               | `ScrollViewProps`                         | All props from `ScrollView`.                         |
+
+#### Scroll Alignment Modes
+
+- **`'auto'`** (default): Minimal scrolling to bring the item into view. Best for keyboard navigation.
+- **`'top'`**: Always aligns the selected item to the top of the viewport.
+- **`'bottom'`**: Always aligns the selected item to the bottom of the viewport.
+- **`'center'`**: Always centers the selected item in the viewport. Best for search/spotlight UX.
+
+### Ref Methods (`ScrollListRef`)
+
+Extends `ScrollViewRef` from `ink-scroll-view`. Access these via `ref.current`.
+
+**Note**: When a `selectedIndex` is set, all scroll methods are constrained to keep the selected item visible. This prevents accidentally scrolling the selection out of view.
+
+| Method              | Signature                                  | Description                                                          |
+| :------------------ | :----------------------------------------- | :------------------------------------------------------------------- |
+| `scrollTo`          | `(y: number) => void`                      | Scroll to a specific offset (constrained to keep selection visible). |
+| `scrollBy`          | `(delta: number) => void`                  | Scroll by a relative amount (constrained).                           |
+| `scrollToTop`       | `() => void`                               | Scroll as far up as possible while keeping selection visible.        |
+| `scrollToBottom`    | `() => void`                               | Scroll as far down as possible while keeping selection visible.      |
+| `getScrollOffset`   | `() => number`                             | Get current scroll offset.                                           |
+| `getContentHeight`  | `() => number`                             | Get total content height.                                            |
+| `getViewportHeight` | `() => number`                             | Get viewport height.                                                 |
+| `getBottomOffset`   | `() => number`                             | Get distance from bottom.                                            |
+| `getItemHeight`     | `(index: number) => number`                | Get a specific item's height.                                        |
+| `getItemPosition`   | `(index: number) => {top, height} \| null` | Get a specific item's position.                                      |
+| `remeasure`         | `() => void`                               | Force remeasurement of all items.                                    |
+| `remeasureItem`     | `(index: number) => void`                  | Force remeasurement of a specific item.                              |
+
+**Large Items**: For items that are larger than the viewport, scrolling is allowed within the item's bounds. This lets users scroll to see different parts of the large item while at least part of it remains visible.
+
+## 💡 Tips
+
+1. **Controlled Component Pattern**: `ScrollList` is a fully controlled component. The parent must manage `selectedIndex` and update it based on user input.
+
+2. **Input Handling**: Use `useInput` from Ink to handle keyboard events and update `selectedIndex` accordingly. The component does NOT handle input internally.
+
+3. **Terminal Resizing**: Ink components don't automatically know when the terminal window resizes. Listen to `process.stdout`'s `resize` event and call `remeasure()` on the ref:
+
+   ```tsx
+   useEffect(() => {
+     const handleResize = () => listRef.current?.remeasure();
+     process.stdout.on("resize", handleResize);
+     return () => process.stdout.off("resize", handleResize);
+   }, []);
+   ```
+
+4. **Dynamic Items**: When items are added or removed, the parent should update `selectedIndex` if necessary:
+   - When adding items at the beginning: `setSelectedIndex(prev => prev + addedCount)`
+   - When removing items: Clamp to valid range: `setSelectedIndex(prev => Math.min(prev, newLength - 1))`
+
+5. **Performance**: `ScrollList` uses `ink-scroll-view` under the hood, so it benefits from the same performance optimizations (item height caching, efficient re-layouts).
+
+## ⚠️ Breaking Changes in v0.4.0
+
+This version introduces a **major architectural change**: `ScrollList` is now a **fully controlled component**.
+
+### Removed Features
+
+The following props have been removed:
+
+- `onSelectionChange` - No longer needed; parent owns the state directly.
+
+The following ref methods have been removed:
+
+- `select(index, mode)` - Use `setSelectedIndex(index)` + `scrollAlignment` prop instead.
+- `selectNext()` - Use `setSelectedIndex(prev => Math.min(prev + 1, length - 1))` instead.
+- `selectPrevious()` - Use `setSelectedIndex(prev => Math.max(prev - 1, 0))` instead.
+- `selectFirst()` - Use `setSelectedIndex(0)` instead.
+- `selectLast()` - Use `setSelectedIndex(length - 1)` instead.
+- `scrollToItem(index, mode)` - Use `selectedIndex` prop instead.
+- `getSelectedIndex()` - Parent already knows the index.
+- `getItemCount()` - Parent already knows the item count.
+
+### Migration Guide
+
+**Before (v0.3.x):**
+
+```tsx
+const listRef = useRef<ScrollListRef>(null);
+const [selectedIndex, setSelectedIndex] = useState(0);
+
+useInput((input, key) => {
+  if (key.downArrow) {
+    const newIndex = listRef.current?.selectNext() ?? 0;
+    setSelectedIndex(newIndex);
+  }
+});
+
+<ScrollList ref={listRef} selectedIndex={selectedIndex} onSelectionChange={setSelectedIndex}>
+  {items.map(...)}
+</ScrollList>
+```
+
+**After (v0.4.0):**
+
+```tsx
+const listRef = useRef<ScrollListRef>(null);
+const [selectedIndex, setSelectedIndex] = useState(0);
+
+useInput((input, key) => {
+  if (key.downArrow) {
+    setSelectedIndex((prev) => Math.min(prev + 1, items.length - 1));
+  }
+});
+
+<ScrollList ref={listRef} selectedIndex={selectedIndex}>
+  {items.map(...)}
+</ScrollList>
+```
+
+### Why This Change?
+
+The controlled component pattern provides:
+
+- **Predictability**: The parent always knows the exact selection state.
+- **Simplicity**: No need to sync internal state with external state.
+- **Flexibility**: The parent has full control over how selection changes.
+- **Testability**: Selection logic lives in the parent and is easy to unit test.
+
+## 🔗 Related Packages
+
+This package is part of a family of Ink scroll components:
+
+| Package                                                                  | Description                                                               |
+| :----------------------------------------------------------------------- | :------------------------------------------------------------------------ |
+| [ink-scroll-view](https://github.com/ByteLandTechnology/ink-scroll-view) | Core scroll container component                                           |
+| [ink-scroll-list](https://github.com/ByteLandTechnology/ink-scroll-list) | A scrollable list with focus management and item selection (this package) |
+| [ink-scroll-bar](https://github.com/ByteLandTechnology/ink-scroll-bar)   | A standalone scrollbar component for any scroll container                 |
+
+## License
+
+MIT

package/node_modules/ink-scroll-list/dist/index.d.ts

@@ -0,0 +1,232 @@
+import * as react from 'react';
+import { ScrollViewProps, ScrollViewRef } from 'ink-scroll-view';
+
+/**
+ * Alignment mode for scrolling to items.
+ *
+ * Determines how the selected item is positioned within the viewport when
+ * the component auto-scrolls to make it visible.
+ *
+ * @remarks
+ * - `'auto'`: Performs minimal scrolling to bring the item into view. If the item
+ *   is above the viewport, scrolls to show its top. If below, scrolls to show its bottom.
+ *   Does not scroll if the item is already fully visible.
+ * - `'top'`: Always aligns the top of the selected item with the top of the viewport.
+ * - `'bottom'`: Always aligns the bottom of the selected item with the bottom of the viewport.
+ * - `'center'`: Always centers the selected item vertically within the viewport.
+ *
+ * All modes respect scroll bounds - the scroll offset will be clamped to valid range
+ * (0 to contentHeight - viewportHeight).
+ */
+type ScrollAlignment = "auto" | "top" | "bottom" | "center";
+/**
+ * Props for the ScrollList component.
+ *
+ * @remarks
+ * Extends {@link ScrollViewProps} from ink-scroll-view and adds externally controlled
+ * selection with automatic scroll-into-view behavior.
+ *
+ * **Key Differences from Previous Versions**:
+ * - Selection state is now fully controlled by the parent (no internal state)
+ * - Removed `onSelectionChange` callback (parent manages state directly)
+ * - Removed imperative selection methods (`select`, `selectNext`, etc.)
+ */
+interface ScrollListProps extends ScrollViewProps {
+    /**
+     * The currently selected item index (controlled by parent).
+     *
+     * @remarks
+     * When this value changes, the component will automatically scroll to ensure
+     * the selected item is visible in the viewport according to the `scrollAlignment` mode.
+     *
+     * **Important Behaviors**:
+     * - The selection state is entirely controlled by the parent component.
+     * - Invalid indices (negative or >= item count) are handled gracefully - no scrolling occurs.
+     * - When `undefined`, the component does not perform auto-scrolling (useful for manual scroll control).
+     * - The component does NOT clamp or modify this value - the parent is responsible for bounds checking.
+     *
+     * @example
+     * ```tsx
+     * const [selectedIndex, setSelectedIndex] = useState(0);
+     *
+     * useInput((input, key) => {
+     *   if (key.downArrow) {
+     *     setSelectedIndex(prev => Math.min(prev + 1, items.length - 1));
+     *   }
+     * });
+     *
+     * <ScrollList selectedIndex={selectedIndex}>
+     *   {items.map((item, i) => <ListItem key={i} selected={i === selectedIndex} />)}
+     * </ScrollList>
+     * ```
+     */
+    selectedIndex?: number;
+    /**
+     * Alignment mode when scrolling to the selected item.
+     *
+     * @remarks
+     * Controls how the selected item is positioned within the viewport when auto-scrolling.
+     *
+     * **Modes**:
+     * - `'auto'`: Minimal scrolling to bring item into view (default). Best for keyboard navigation.
+     * - `'top'`: Align item to the top of the viewport. Good for "jump to" navigation.
+     * - `'bottom'`: Align item to the bottom of the viewport.
+     * - `'center'`: Align item to the center of the viewport. Best for search result highlighting.
+     *
+     * **Examples**:
+     * ```tsx
+     * // Default auto behavior - minimal scrolling
+     * <ScrollList selectedIndex={index} scrollAlignment="auto" />
+     *
+     * // Always center the selected item - good for search/spotlight UX
+     * <ScrollList selectedIndex={searchResultIndex} scrollAlignment="center" />
+     * ```
+     *
+     * @defaultValue `'auto'`
+     */
+    scrollAlignment?: ScrollAlignment;
+}
+/**
+ * Ref interface for controlling the ScrollList programmatically.
+ *
+ * @remarks
+ * Extends {@link ScrollViewRef} from ink-scroll-view. Since selection is now controlled
+ * externally via props, this interface no longer includes selection-related methods.
+ *
+ * **Scroll Constraint Behavior**:
+ * When a `selectedIndex` is set, all scroll methods (`scrollTo`, `scrollBy`, `scrollToTop`,
+ * `scrollToBottom`) are constrained to keep the selected item visible in the viewport.
+ * This prevents accidentally scrolling the selection out of view.
+ *
+ * For items larger than the viewport, scrolling is allowed within the item's bounds,
+ * letting users view different parts of the large item while keeping at least part
+ * of it visible.
+ *
+ * **Available Methods** (inherited from ScrollViewRef):
+ * - `scrollTo(y)`: Scroll to a specific offset (constrained if selected item exists)
+ * - `scrollBy(delta)`: Scroll by a relative amount (constrained)
+ * - `scrollToTop()`: Scroll as far up as possible while keeping selection visible
+ * - `scrollToBottom()`: Scroll as far down as possible while keeping selection visible
+ * - `getScrollOffset()`: Get the current scroll offset
+ * - `getContentHeight()`: Get the total content height
+ * - `getViewportHeight()`: Get the viewport height
+ * - `getBottomOffset()`: Get the offset from the bottom
+ * - `getItemHeight(index)`: Get a specific item's height
+ * - `getItemPosition(index)`: Get a specific item's position (top and height)
+ * - `remeasure()`: Force remeasurement of all items
+ * - `remeasureItem(index)`: Force remeasurement of a specific item
+ *
+ * **Note**: Unlike previous versions, there are no selection methods (select, selectNext, etc.)
+ * as selection is now controlled externally via the `selectedIndex` prop.
+ */
+interface ScrollListRef extends ScrollViewRef {
+}
+/**
+ * A scrollable list with externally controlled selection.
+ *
+ * @remarks
+ * This component extends {@link ScrollView} from ink-scroll-view to provide:
+ * - **Externally controlled selection**: Selection state is managed by the parent via `selectedIndex` prop
+ * - **Automatic scroll-into-view**: When `selectedIndex` changes, the component scrolls to ensure visibility
+ * - **Configurable alignment**: Control how selected items are positioned within the viewport
+ * - **Responsive to layout changes**: Maintains selected item visibility when viewport or content changes
+ *
+ * ## Design Philosophy
+ *
+ * ScrollList follows the "controlled component" pattern where the parent component owns all state.
+ * This provides several benefits:
+ * - **Predictable behavior**: The parent always knows the current selection
+ * - **Easy integration**: Works seamlessly with state management libraries
+ * - **Flexible input handling**: Parent decides how keyboard/mouse events affect selection
+ * - **Testable**: Selection logic lives in the parent and is easy to unit test
+ *
+ * ## Automatic Scroll Behavior
+ *
+ * The component automatically scrolls to keep the selected item visible in these scenarios:
+ * 1. When `selectedIndex` prop changes
+ * 2. When viewport size changes (e.g., terminal resize)
+ * 3. When content height changes (e.g., items added/removed)
+ * 4. When an item's height changes and it affects the selected item's position
+ *
+ * ## Important Caveats
+ *
+ * - **No input handling**: This component does NOT handle keyboard input.
+ *   Use `useInput` from Ink to update `selectedIndex` in the parent.
+ * - **No resize detection**: Does NOT automatically respond to terminal resize.
+ *   Listen to `process.stdout`'s `resize` event and call `remeasure()` on the ref.
+ * - **Parent manages bounds**: The component does NOT clamp `selectedIndex`.
+ *   The parent should ensure the value is within valid range [0, itemCount - 1].
+ *
+ * @example
+ * ### Basic Usage with Keyboard Navigation
+ * ```tsx
+ * import React, { useRef, useState } from 'react';
+ * import { Box, Text, useInput } from 'ink';
+ * import { ScrollList, ScrollListRef } from 'ink-scroll-list';
+ *
+ * const Demo = () => {
+ *   const listRef = useRef<ScrollListRef>(null);
+ *   const [selectedIndex, setSelectedIndex] = useState(0);
+ *   const items = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];
+ *
+ *   // Handle keyboard navigation
+ *   useInput((input, key) => {
+ *     if (key.downArrow) {
+ *       setSelectedIndex(prev => Math.min(prev + 1, items.length - 1));
+ *     }
+ *     if (key.upArrow) {
+ *       setSelectedIndex(prev => Math.max(prev - 1, 0));
+ *     }
+ *     if (input === 'g') {
+ *       setSelectedIndex(0); // Go to first
+ *     }
+ *     if (input === 'G') {
+ *       setSelectedIndex(items.length - 1); // Go to last
+ *     }
+ *   });
+ *
+ *   return (
+ *     <ScrollList
+ *       ref={listRef}
+ *       height={5}
+ *       selectedIndex={selectedIndex}
+ *     >
+ *       {items.map((item, i) => (
+ *         <Box key={i}>
+ *           <Text color={i === selectedIndex ? 'blue' : 'white'}>
+ *             {i === selectedIndex ? '> ' : '  '}{item}
+ *           </Text>
+ *         </Box>
+ *       ))}
+ *     </ScrollList>
+ *   );
+ * };
+ * ```
+ *
+ * @example
+ * ### With Different Alignment Modes
+ * ```tsx
+ * // Center alignment - great for search results or spotlight features
+ * <ScrollList
+ *   height={10}
+ *   selectedIndex={searchResultIndex}
+ *   scrollAlignment="center"
+ * >
+ *   {results.map((result, i) => (
+ *     <SearchResult key={i} result={result} highlighted={i === searchResultIndex} />
+ *   ))}
+ * </ScrollList>
+ *
+ * // Top alignment - always shows selected item at top
+ * <ScrollList
+ *   height={5}
+ *   selectedIndex={selectedIndex}
+ *   scrollAlignment="top"
+ * >
+ *   {items.map((item, i) => <Item key={i} {...item} />)}
+ * </ScrollList>
+ * ```
+ */
+declare const ScrollList: react.ForwardRefExoticComponent<ScrollListProps & react.RefAttributes<ScrollListRef>>;
+
+export { type ScrollAlignment, ScrollList, type ScrollListProps, type ScrollListRef };