@oh-my-pi/pi-tui 18.2.3 → 18.2.5

package/src/tools/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Built-in tool renderer registry: maps tool names to their transcript renderers.
+ * `ToolExecutionComponent` and the `xd://` dispatch look renderers up here;
+ * tools without an entry fall back to `renderDefaultToolExecution`.
+ */
+import { askToolRenderer } from "./ask";
+import { astEditToolRenderer } from "./ast-edit";
+import { astGrepToolRenderer } from "./ast-grep";
+import { bashToolRenderer } from "./bash";
+import { debugToolRenderer } from "./debug";
+import { editToolRenderer } from "./edit";
+import { evalToolRenderer } from "./eval";
+import { githubToolRenderer } from "./github";
+import { globToolRenderer } from "./glob";
+import { goalToolRenderer } from "./goal";
+import { grepToolRenderer } from "./grep";
+import { hubToolRenderer } from "./hub";
+import { lspToolRenderer } from "./lsp";
+import { recallToolRenderer, reflectToolRenderer, retainToolRenderer } from "./memory";
+import { readToolRenderer } from "./read";
+import type { ToolRenderer } from "./renderer";
+import { resolveRenderer } from "./resolve";
+import { taskToolRenderer } from "./task";
+import { thinkToolRenderer } from "./think";
+import { todoToolRenderer } from "./todo";
+import { createVibeToolRenderer } from "./vibe";
+import { webSearchToolRenderer } from "./web-search";
+import { writeToolRenderer } from "./write";
+import { setXdevRendererLookup } from "./xdev";
+
+export * from "./renderer";
+
+/** Renderers keyed by tool name (plus `apply_patch`/`reject` aliases that share a renderer). */
+export const toolRenderers: Record<string, ToolRenderer> = {
+	ask: askToolRenderer,
+	ast_grep: astGrepToolRenderer,
+	ast_edit: astEditToolRenderer,
+	bash: bashToolRenderer,
+	debug: debugToolRenderer,
+	eval: evalToolRenderer,
+	edit: editToolRenderer,
+	apply_patch: editToolRenderer,
+	glob: globToolRenderer,
+	grep: grepToolRenderer,
+	lsp: lspToolRenderer,
+	hub: hubToolRenderer,
+	read: readToolRenderer,
+	// Keyed by xd:// resolution-device names: the write dispatch delegates here
+	// by dispatch tool, and historical `resolve` tool transcripts still render
+	// through the `resolve` entry. Both devices carry the same ResolveDetails.
+	resolve: resolveRenderer,
+	reject: resolveRenderer,
+	retain: retainToolRenderer,
+	recall: recallToolRenderer,
+	reflect: reflectToolRenderer,
+	task: taskToolRenderer,
+	think: thinkToolRenderer,
+	todo: todoToolRenderer,
+	github: githubToolRenderer,
+	goal: goalToolRenderer,
+	web_search: webSearchToolRenderer,
+	vibe_spawn: createVibeToolRenderer("spawn"),
+	vibe_send: createVibeToolRenderer("send"),
+	vibe_wait: createVibeToolRenderer("wait"),
+	vibe_kill: createVibeToolRenderer("kill"),
+	vibe_list: createVibeToolRenderer("list"),
+	write: writeToolRenderer,
+};
+
+// Wire the xd:// render delegation without the xdev module importing this registry.
+setXdevRendererLookup(name => toolRenderers[name]);

package/src/tools/json-tree.ts

@@ -0,0 +1,388 @@
+/**
+ * JSON tree rendering utilities shared across tool renderers.
+ */
+import { INTENT_FIELD } from "@oh-my-pi/pi-wire";
+import { sanitizeText } from "@oh-my-pi/pi-utils";
+import { TreeView, treeRowPrefix } from "../components/tree-view";
+import { truncateToWidth } from "../render/render-utils";
+import type { Theme, ThemeColor } from "../theme/theme";
+
+/** Max depth for JSON tree rendering */
+export const JSON_TREE_MAX_DEPTH_COLLAPSED = 2;
+/** Maximum expanded JSON tree depth. */
+export const JSON_TREE_MAX_DEPTH_EXPANDED = 6;
+/** Maximum collapsed JSON tree rows. */
+export const JSON_TREE_MAX_LINES_COLLAPSED = 6;
+/** Maximum expanded JSON tree rows. */
+export const JSON_TREE_MAX_LINES_EXPANDED = 200;
+/** Maximum collapsed JSON scalar width. */
+export const JSON_TREE_SCALAR_LEN_COLLAPSED = 60;
+/** Maximum expanded JSON scalar width. */
+export const JSON_TREE_SCALAR_LEN_EXPANDED = 2000;
+
+const HIDDEN_ARG_KEYS = { [INTENT_FIELD]: 1, __partialJson: 1 };
+const DEFAULT_HIDDEN_ROOT_KEYS: readonly string[] = Object.keys(HIDDEN_ARG_KEYS);
+
+const ARGS_INLINE_PAIR_SEP = ", ";
+const ARGS_INLINE_PAIR_SEP_WIDTH = Bun.stringWidth(ARGS_INLINE_PAIR_SEP);
+const ARGS_INLINE_MORE = "…";
+const ARGS_INLINE_MORE_WIDTH = Bun.stringWidth(ARGS_INLINE_MORE);
+/** Minimal value footprint (quotes + a couple chars) reserved for each not-yet-rendered key. */
+const ARGS_INLINE_TAIL_VALUE_RESERVE = 4;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Sanitization, string summary, and budgeting policy for inline JSON. */
+export interface InlineFormatOptions {
+	sanitizeText?: (text: string) => string;
+	multilineSummary?: boolean;
+	/** Character-count output budget, retaining the first pair even when oversized. */
+	characterBudget?: boolean;
+}
+
+/** Format a scalar with optional sanitized multiline summaries. */
+export function formatScalar(value: unknown, maxLen: number, options: InlineFormatOptions = {}): string {
+	if (value === null) return "null";
+	if (value === undefined) return "undefined";
+	if (typeof value === "boolean") return String(value);
+	if (typeof value === "number") return String(value);
+	if (typeof value === "string") {
+		const text = options.sanitizeText?.(value) ?? value;
+		if (options.multilineSummary) {
+			const lines = text.split("\n");
+			const firstLine = lines[0].trim();
+			if (!firstLine) return `"" (${lines.length} lines)`;
+			const preview = truncateToWidth(firstLine, maxLen);
+			return lines.length > 1 ? `"${preview}…" (${lines.length} lines)` : `"${preview}"`;
+		}
+		const escaped = text.replace(/\n/g, "\\n").replace(/\t/g, "\\t");
+		const truncated = truncateToWidth(escaped, maxLen);
+		return `"${truncated}"`;
+	}
+	if (Array.isArray(value)) return `[${value.length} items]`;
+	if (typeof value === "object") {
+		const keys = Object.keys(value);
+		return `{${keys.length} keys}`;
+	}
+	const text = String(value);
+	return options.sanitizeText?.(text) ?? text;
+}
+
+/** Format args inline with either display-cell or legacy output character budgeting. */
+export function formatArgsInline(
+	args: Record<string, unknown>,
+	maxWidth: number,
+	options: InlineFormatOptions = {},
+): string {
+	if (options.characterBudget) {
+		const pairs: string[] = [];
+		let length = 0;
+		for (const key in args) {
+			if (!Object.hasOwn(args, key)) continue;
+			const pair = `${options.sanitizeText?.(key) ?? key}=${formatScalar(args[key], 24, options)}`;
+			const added = pair.length + (pairs.length > 0 ? 2 : 0);
+			if (length + added > maxWidth && pairs.length > 0) {
+				pairs.push("…");
+				break;
+			}
+			pairs.push(pair);
+			length += added;
+		}
+		return pairs.join(", ");
+	}
+	const keys: string[] = [];
+	for (const key in args) {
+		if (key in HIDDEN_ARG_KEYS) continue;
+		keys.push(key);
+	}
+	let result = "";
+	let width = 0;
+	for (let i = 0; i < keys.length; i++) {
+		const rawKey = keys[i];
+		const key = options.sanitizeText?.(rawKey) ?? rawKey;
+		const value = args[rawKey];
+		const sep = width > 0 ? ARGS_INLINE_PAIR_SEP : "";
+		const sepW = width > 0 ? ARGS_INLINE_PAIR_SEP_WIDTH : 0;
+		const current = width + sepW;
+		const cap = maxWidth - current - ARGS_INLINE_MORE_WIDTH;
+		if (cap <= 0) {
+			return `${result}${ARGS_INLINE_MORE}`;
+		}
+		// Reserve each still-pending key's minimal footprint (sep + name + `=` +
+		// a short value) so a long value can't starve the keys that follow it.
+		let tailReserve = 0;
+		for (let j = i + 1; j < keys.length; j++) {
+			const tailKey = options.sanitizeText?.(keys[j]) ?? keys[j];
+			tailReserve += ARGS_INLINE_PAIR_SEP_WIDTH + Bun.stringWidth(tailKey) + 1 + ARGS_INLINE_TAIL_VALUE_RESERVE;
+		}
+		// Budget the whole `key=value` piece against the width left after the
+		// tail reserve, then back out the value's share. The last key reserves
+		// nothing and fills the line.
+		const pieceBudget = Math.min(cap, maxWidth - current - tailReserve);
+		const valueMaxLen = Math.max(1, pieceBudget - Bun.stringWidth(key) - 3);
+		const valueStr = formatScalar(value, valueMaxLen, options);
+		const piece = `${key}=${valueStr}`;
+		const pieceW = Bun.stringWidth(piece);
+		if (pieceW > pieceBudget) {
+			return `${result}${sep}${truncateToWidth(piece, cap)}`;
+		}
+		result += sep + piece;
+		width = current + pieceW;
+	}
+	return result;
+}
+
+const OUTPUT_INLINE_OPTIONS: InlineFormatOptions = {
+	sanitizeText,
+	multilineSummary: true,
+	characterBudget: true,
+};
+
+/** Summarize a task's structured output without expanding its JSON tree. */
+export function formatOutputInline(data: unknown, maxWidth = 80): string {
+	const options = OUTPUT_INLINE_OPTIONS;
+	if (data === null || data === undefined) return "Output: none";
+	if (typeof data !== "object") return `Output: ${formatScalar(data, 60, options)}`;
+	if (Array.isArray(data)) {
+		if (data.length === 0) return "Output: []";
+		return `Output: [${data.length} items] ${formatScalar(data[0], 40, options)}${data.length > 1 ? "…" : ""}`;
+	}
+	return `Output: ${formatArgsInline(data as Record<string, unknown>, maxWidth - "Output: ".length, options) || "{}"}`;
+}
+
+/** JSON hierarchy policy accepted by {@link renderJsonTreeLines}. */
+export interface JsonTreeRenderOptions {
+	maxDepth: number;
+	maxLines: number;
+	maxScalarLen: number;
+	/** Sanitize object keys and string/scalar text before styling. */
+	sanitizeText?: (text: string) => string;
+	/** Root object keys omitted from display. Defaults to internal tool argument metadata. */
+	hiddenRootKeys?: readonly string[];
+	/** Preserve embedded newlines as continuation rows. Defaults to true. */
+	multilineStrings?: boolean;
+	/** Escape inline tabs/newlines as JSON-style sequences. Defaults to true. */
+	escapeStringWhitespace?: boolean;
+	/**
+	 * Root row gutter. `hooked` (default) attaches the tree to the block above:
+	 * the first root draws `└ •`, the rest ` •`, and nested rows branch from
+	 * under the bullet. `siblings` draws standard `├─`/`└─` root connectors.
+	 */
+	rootConnectors?: "hooked" | "siblings";
+}
+
+type JsonTreeNodeKind = "array" | "object" | "scalar" | "placeholder";
+
+interface JsonTreeNode {
+	id: number;
+	key: string | undefined;
+	value: unknown;
+	depth: number;
+	kind: JsonTreeNodeKind;
+	placeholder?: "…";
+	children?: readonly JsonTreeNode[];
+}
+
+function jsonNodeKind(value: unknown): JsonTreeNodeKind {
+	if (Array.isArray(value)) return "array";
+	if (isRecord(value)) return "object";
+	return "scalar";
+}
+
+/**
+ * Render a JSON value as bounded tree lines. The positional form remains the
+ * public tool-renderer contract; the options form exposes sanitization and root
+ * connector policy for specialized adapters such as nested task output.
+ */
+export function renderJsonTreeLines(
+	value: unknown,
+	theme: Theme,
+	maxDepth: number,
+	maxLines: number,
+	maxScalarLen: number,
+): { lines: string[]; truncated: boolean };
+export function renderJsonTreeLines(
+	value: unknown,
+	theme: Theme,
+	options: JsonTreeRenderOptions,
+): { lines: string[]; truncated: boolean };
+export function renderJsonTreeLines(
+	value: unknown,
+	theme: Theme,
+	optionsOrMaxDepth: JsonTreeRenderOptions | number,
+	maxLinesArg?: number,
+	maxScalarLenArg?: number,
+): { lines: string[]; truncated: boolean } {
+	const options: JsonTreeRenderOptions =
+		typeof optionsOrMaxDepth === "number"
+			? {
+					maxDepth: optionsOrMaxDepth,
+					maxLines: maxLinesArg ?? JSON_TREE_MAX_LINES_EXPANDED,
+					maxScalarLen: maxScalarLenArg ?? JSON_TREE_SCALAR_LEN_EXPANDED,
+				}
+			: optionsOrMaxDepth;
+	const maxDepth = Math.max(0, Math.trunc(options.maxDepth));
+	const maxLines = Math.max(0, Math.trunc(options.maxLines));
+	const maxScalarLen = Math.max(0, Math.trunc(options.maxScalarLen));
+	const sanitize = options.sanitizeText ?? (text => text);
+	const hiddenRootKeys = options.hiddenRootKeys ?? DEFAULT_HIDDEN_ROOT_KEYS;
+	const multilineStrings = options.multilineStrings ?? true;
+	const escapeStringWhitespace = options.escapeStringWhitespace ?? true;
+	const hookedRoots = (options.rootConnectors ?? "hooked") === "hooked";
+	let nextId = 0;
+
+	const node = (nodeValue: unknown, key: string | undefined, depth: number): JsonTreeNode => ({
+		id: nextId++,
+		key,
+		value: nodeValue,
+		depth,
+		kind: jsonNodeKind(nodeValue),
+	});
+
+	let roots: readonly JsonTreeNode[];
+	if (isRecord(value)) {
+		const objectRoots: JsonTreeNode[] = [];
+		for (const key in value) {
+			if (!hiddenRootKeys.includes(key)) objectRoots.push(node(value[key], key, 1));
+		}
+		roots = objectRoots;
+	} else if (Array.isArray(value)) {
+		roots = value.map((child, index) => node(child, `[${index}]`, 1));
+	} else {
+		roots = [node(value, undefined, 0)];
+	}
+
+	const prefixStyle = { vertical: (symbol: string) => symbol };
+	const hook = theme.tree.hook;
+	const hookPad = " ".repeat(Bun.stringWidth(hook));
+	const bullet = theme.format.bullet;
+	// Nested rows drop the root's three-cell gutter and branch from under the root label.
+	const rootGutter = `${hookPad} ${" ".repeat(Bun.stringWidth(bullet))} `;
+	let renderedLineCount = 0;
+	let scalarTruncated = false;
+
+	const tree = new TreeView<JsonTreeNode, number>({
+		roots,
+		getKey: item => item.id,
+		getChildren: item => {
+			if (item.children) return item.children;
+			let children: readonly JsonTreeNode[] = [];
+			if (item.kind === "array" && Array.isArray(item.value)) {
+				const values = item.value;
+				if (values.length === 0) {
+					children = [];
+				} else if (item.depth >= maxDepth) {
+					children = [
+						{
+							id: nextId++,
+							key: undefined,
+							value: undefined,
+							depth: item.depth + 1,
+							kind: "placeholder",
+							placeholder: "…",
+						},
+					];
+				} else {
+					children = values.map((child, index) => node(child, `[${index}]`, item.depth + 1));
+				}
+			} else if (item.kind === "object" && isRecord(item.value)) {
+				const record = item.value;
+				const keys = Object.keys(record);
+				if (item.depth >= maxDepth) {
+					children = [
+						{
+							id: nextId++,
+							key: undefined,
+							value: undefined,
+							depth: item.depth + 1,
+							kind: "placeholder",
+							placeholder: "…",
+						},
+					];
+				} else if (keys.length === 0) {
+					children = [];
+				} else {
+					const objectChildren: JsonTreeNode[] = [];
+					for (const key in record) objectChildren.push(node(record[key], key, item.depth + 1));
+					children = objectChildren;
+				}
+			}
+			item.children = children;
+			return children;
+		},
+		maxItems: maxLines + 1,
+		maxLines,
+		theme,
+		renderPrefix: itemRow => {
+			if (!hookedRoots) return treeRowPrefix(itemRow, theme, prefixStyle);
+			if (itemRow.ancestors.length === 0) {
+				const lead = itemRow.siblingIndex === 0 ? theme.fg("dim", hook) : hookPad;
+				return { first: `${lead} ${theme.fg("dim", bullet)} `, continuation: rootGutter };
+			}
+			const inner = treeRowPrefix({ ...itemRow, ancestors: itemRow.ancestors.slice(1) }, theme, prefixStyle);
+			return { first: `${rootGutter}${inner.first}`, continuation: `${rootGutter}${inner.continuation}` };
+		},
+		renderRow: item => {
+			let body: readonly string[];
+			const displayKey = item.key ? sanitize(item.key) : undefined;
+			const label = theme.fg(
+				"muted",
+				displayKey || (item.kind === "array" ? "array" : item.kind === "object" ? "object" : "value"),
+			);
+			if (item.kind === "placeholder") {
+				body = [theme.fg("dim", item.placeholder ?? "…")];
+			} else if (item.kind === "array") {
+				body = [`${label} ${theme.fg("dim", `[${(item.value as unknown[]).length}]`)}`];
+			} else if (item.kind === "object") {
+				body = [`${label} ${theme.fg("dim", `{${Object.keys(item.value as object).length}}`)}`];
+			} else if (typeof item.value === "string") {
+				const sanitized = sanitize(item.value);
+				if (multilineStrings && sanitized.includes("\n")) {
+					const sourceLines = sanitized.split("\n");
+					const available = Math.max(1, maxLines - renderedLineCount);
+					const displayedCount = Math.min(sourceLines.length, Math.max(1, available - 1));
+					const head = `${label}: `;
+					// Continuation rows sit under the opening quote.
+					const indent = " ".repeat(Bun.stringWidth(Bun.stripANSI(head)) + 1);
+					const scalarLines = [
+						`${head}${theme.fg("syntaxString", `"${truncateToWidth(sourceLines[0] ?? "", maxScalarLen)}`)}`,
+					];
+					for (let index = 1; index < displayedCount; index++) {
+						scalarLines.push(
+							`${indent}${theme.fg("syntaxString", truncateToWidth(sourceLines[index] ?? "", maxScalarLen))}`,
+						);
+					}
+					if (sourceLines.length > displayedCount) {
+						scalarTruncated = true;
+						scalarLines.push(
+							`${indent}${theme.fg("dim", `…(${sourceLines.length - displayedCount} more lines)"`)}`,
+						);
+					} else {
+						const lastIndex = scalarLines.length - 1;
+						scalarLines[lastIndex] = `${scalarLines[lastIndex]}${theme.fg("syntaxString", '"')}`;
+					}
+					body = scalarLines;
+				} else {
+					const scalar = escapeStringWhitespace
+						? formatScalar(sanitized, maxScalarLen)
+						: `"${truncateToWidth(sanitized, maxScalarLen)}"`;
+					body = [`${label}: ${theme.fg("syntaxString", scalar)}`];
+				}
+			} else {
+				const color: ThemeColor =
+					typeof item.value === "number"
+						? "syntaxNumber"
+						: typeof item.value === "boolean" || item.value === null || item.value === undefined
+							? "syntaxKeyword"
+							: "dim";
+				body = [`${label}: ${theme.fg(color, sanitize(formatScalar(item.value, maxScalarLen)))}`];
+			}
+			renderedLineCount += body.length;
+			return body;
+		},
+	});
+	const rendered = tree.renderWithState(Number.POSITIVE_INFINITY);
+	return { lines: [...rendered.lines], truncated: rendered.truncated || scalarTruncated };
+}

package/src/tools/line-ranges.ts

@@ -0,0 +1,98 @@
+import { ToolError } from "./tool-errors";
+
+/**
+ * Inclusive line range describing one selector segment (e.g. `50-100`,
+ * `301-`, or `50+10`). `endLine` is `undefined` for open-ended ranges.
+ */
+export interface LineRange {
+	startLine: number;
+	endLine: number | undefined;
+}
+
+/** Shared line-range grammar for selector recognition and parsing. */
+export const LINE_RANGE_CHUNK_SOURCE = String.raw`L?(\d+)(?:(\.\.|[-+])L?(\d+)?)?`;
+const LINE_RANGE_CHUNK_RE = new RegExp(`^${LINE_RANGE_CHUNK_SOURCE}$`, "i");
+
+/** Parse a single `N`, `N-M`, `N-`, `N+K`, or `..`-aliased (`N..M`, `N..`) chunk. Throws via {@link ToolError} on invalid bounds. */
+export function parseLineRangeChunk(sel: string): LineRange | null {
+	const lineMatch = LINE_RANGE_CHUNK_RE.exec(sel);
+	if (!lineMatch) return null;
+	const rawStart = Number.parseInt(lineMatch[1]!, 10);
+	if (rawStart < 1) {
+		throw new ToolError("Line selector 0 is invalid; lines are 1-indexed. Use :1.");
+	}
+	// `..` is a forgiving alias for `-` (e.g. `2724..2727` == `2724-2727`).
+	const sep = lineMatch[2] === ".." ? "-" : lineMatch[2];
+	const rhs = lineMatch[3] ? Number.parseInt(lineMatch[3], 10) : undefined;
+	let rawEnd: number | undefined;
+	if (sep === "+") {
+		if (rhs === undefined || rhs < 1) {
+			throw new ToolError(`Invalid range ${rawStart}+${rhs ?? 0}: count must be >= 1.`);
+		}
+		rawEnd = rawStart + rhs - 1;
+	} else if (sep === "-") {
+		// `301-` is shorthand for "from 301 onward" — equivalent to bare `301`.
+		if (rhs !== undefined) {
+			if (rhs < rawStart) {
+				throw new ToolError(`Invalid range ${rawStart}-${rhs}: end must be >= start.`);
+			}
+			rawEnd = rhs;
+		}
+	}
+	return { startLine: rawStart, endLine: rawEnd };
+}
+
+/**
+ * Parse a comma-separated list of line ranges (e.g. `5-16,960-973`). Returns
+ * the ranges in ascending order with overlapping/adjacent ranges merged so
+ * downstream consumers can stream the file in a single forward pass per range.
+ */
+export function parseLineRanges(sel: string): [LineRange, ...LineRange[]] | null {
+	const chunks = sel.split(",");
+	const parsed: LineRange[] = [];
+	for (const chunk of chunks) {
+		const range = parseLineRangeChunk(chunk);
+		if (!range) return null;
+		parsed.push(range);
+	}
+	if (parsed.length === 0) return null;
+	parsed.sort((a, b) => a.startLine - b.startLine);
+
+	const merged: LineRange[] = [parsed[0]];
+	for (let i = 1; i < parsed.length; i++) {
+		const current = parsed[i];
+		const last = merged[merged.length - 1];
+		// Open-ended (endLine undefined) means "to EOF" — any later range is absorbed.
+		if (last.endLine === undefined) continue;
+		// Merge when current starts within (or immediately after) the last range.
+		if (current.startLine <= last.endLine + 1) {
+			if (current.endLine === undefined || current.endLine > last.endLine) {
+				merged[merged.length - 1] = { startLine: last.startLine, endLine: current.endLine };
+			}
+			continue;
+		}
+		merged.push(current);
+	}
+	return merged as [LineRange, ...LineRange[]];
+}
+
+/**
+ * Extract the line-range component from a read-tool selector that may also
+ * carry a verbatim/index display mode (`raw`, `conflicts`) — alone or compounded
+ * with a range (`raw:50-100`, `50-100:raw`). Returns the parsed ranges when the
+ * selector names any, otherwise `undefined` (pure `raw`/`conflicts`/none).
+ *
+ * Used by content search, which honors line ranges as a match filter but has no
+ * use for verbatim/conflict display modes — so those selectors are accepted and
+ * treated as an unfiltered, whole-resource search rather than rejected.
+ */
+export function selectorLineRanges(sel: string | undefined): [LineRange, ...LineRange[]] | undefined {
+	if (!sel) return undefined;
+	for (const chunk of sel.split(":")) {
+		const lower = chunk.toLowerCase();
+		if (lower === "raw" || lower === "conflicts") continue;
+		const ranges = parseLineRanges(chunk);
+		if (ranges) return ranges;
+	}
+	return undefined;
+}

package/src/tools/list-limit.ts

@@ -0,0 +1,43 @@
+import type { LimitsMeta } from "./output-meta";
+
+/** Items retained after applying output limits and their metadata. */
+export interface ListLimitResult<T> {
+	items: T[];
+	limitReached?: number;
+	meta: Partial<LimitsMeta>;
+}
+
+/** Limits applied to result lists and display previews. */
+export interface ListLimitOptions {
+	limit?: number;
+	headLimit?: number;
+	limitType?: "match" | "result";
+}
+
+/** Apply result and preview limits while retaining truncation metadata. */
+export function applyListLimit<T>(items: T[], options: ListLimitOptions): ListLimitResult<T> {
+	const meta: Partial<LimitsMeta> = {};
+	const limitType = options.limitType ?? "result";
+	const effectiveLimit = options.limit !== undefined && options.limit > 0 ? options.limit : undefined;
+	const effectiveHeadLimit = options.headLimit !== undefined && options.headLimit > 0 ? options.headLimit : undefined;
+	let limited = items;
+	let limitReached: number | undefined;
+
+	if (effectiveLimit !== undefined && items.length >= effectiveLimit) {
+		limited = items.slice(0, effectiveLimit);
+		limitReached = effectiveLimit;
+		const suggestion = effectiveLimit * 2;
+		if (limitType === "match") {
+			meta.matchLimit = { reached: effectiveLimit, suggestion };
+		} else {
+			meta.resultLimit = { reached: effectiveLimit, suggestion };
+		}
+	}
+
+	if (effectiveHeadLimit !== undefined && limited.length > effectiveHeadLimit) {
+		limited = limited.slice(0, effectiveHeadLimit);
+		meta.headLimit = { reached: effectiveHeadLimit, suggestion: effectiveHeadLimit * 2 };
+	}
+
+	return { items: limited, limitReached, meta };
+}