pi-hashline-edit-pro 7.0.0 → 7.1.0

package/src/outline-tool.ts

@@ -0,0 +1,184 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { Text } from "@earendil-works/pi-tui";
+import { buildFileOutline } from "./outline";
+import { MAX_HASH_LINES } from "./hashline";
+import { loadFileKindAndText } from "./file-kind";
+import { readNormFile, safeSnapId } from "./file-reader";
+import { serveRows } from "./served";
+import { toCwd, toDisplayPath } from "./paths";
+import { formatAnchorReclaimNotice, takeReclaimedPaths, withAnchorSession } from "./anchor-registry";
+import { valAccess, valKind } from "./validation";
+import { abortIf, isRec, makePrepareArguments, rejectUnknownFields, splitLines } from "./utils";
+import { loadP, loadGuidelines } from "./prompts";
+import { DEFAULT_EDIT_FLAGS, type EditToolFlags } from "./edit-common";
+import { anchoredLine, outlineResultSchema, withStructuredErrors, type OutlineStructured } from "./structured";
+
+const OUTLINE_DEFAULT_DEPTH = 2;
+export const OUTLINE_MAX_DEPTH = 10;
+
+export interface OutlineDetails {
+	truncated?: boolean;
+	complete?: boolean;
+	snapshotId?: string;
+	metrics?: { rows: number; truncated: boolean };
+}
+
+function buildOutlineToolSchema(codemode: boolean) {
+	return Type.Object({
+		path: Type.String({
+			description: "Path to the file to outline (relative or absolute).",
+		}),
+		depth: Type.Optional(
+			Type.Integer({
+				minimum: 0,
+				maximum: OUTLINE_MAX_DEPTH,
+				description: `Nesting depth to show: 0 lists top-level symbols only, 1 adds their members (default 2, maximum ${OUTLINE_MAX_DEPTH}).`,
+			}),
+		),
+		...(codemode
+			? {
+				anchors: Type.Optional(
+					Type.Boolean({
+						description: "Return { text, lines, notices } with editable anchors instead of the plain outline text to a codemode script.",
+					}),
+				),
+			}
+			: {}),
+	}, { additionalProperties: true });
+}
+
+export function outlineDepth(value: unknown): number {
+	if (value === undefined) return OUTLINE_DEFAULT_DEPTH;
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > OUTLINE_MAX_DEPTH) {
+		throw new Error(`[E_BAD_SHAPE] Outline request field "depth" must be an integer from 0 to ${OUTLINE_MAX_DEPTH}.`);
+	}
+	return value;
+}
+
+export interface OutlineReq {
+	path: string;
+	depth: number;
+	anchors: boolean;
+}
+
+const OUTLINE_KEYS = new Set(["path", "depth", "anchors"]);
+
+export function normOutlineReq(request: unknown, allowAnchors = false): OutlineReq {
+	if (!isRec(request)) {
+		throw new Error("[E_BAD_SHAPE] Outline request must be an object.");
+	}
+	rejectUnknownFields(request, OUTLINE_KEYS, "Outline request");
+	if (typeof request.path !== "string" || request.path.length === 0) {
+		throw new Error('[E_BAD_SHAPE] Outline request requires a non-empty "path" string.');
+	}
+	if (request.anchors !== undefined) {
+		if (typeof request.anchors !== "boolean") {
+			throw new Error('[E_BAD_SHAPE] Outline request field "anchors" must be a boolean when provided.');
+		}
+		if (!allowAnchors) {
+			throw new Error('[E_BAD_SHAPE] Outline request field "anchors" is only valid in a codemode session.');
+		}
+	}
+	return { path: request.path, depth: outlineDepth(request.depth), anchors: request.anchors === true };
+}
+
+export function regOutline(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FLAGS): void {
+	const prompted = {
+		description: loadP("../tool-prompts/outline.md"),
+		snippet: loadP("../tool-prompts/outline-snippet.md"),
+		guidelines: loadGuidelines("../tool-prompts/outline-guidelines.md").map((guideline) => guideline.text),
+	};
+	if (flags.codemode) prompted.guidelines.push("`outline`: a codemode script receives the served outline text; pass `anchors: true` to receive `{ text, lines, notices }` with editable anchors.");
+	pi.registerTool({
+		name: "outline",
+		defaultActive: false,
+		label: "Outline",
+		description: prompted.description,
+		promptSnippet: prompted.snippet,
+		promptGuidelines: prompted.guidelines,
+		prepareArguments: makePrepareArguments(),
+		parameters: buildOutlineToolSchema(flags.codemode),
+		outputSchema: outlineResultSchema,
+		executionMode: "sequential",
+		renderCall(args: any, theme: any, context: any) {
+			const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+			const path = typeof args?.path === "string" && args.path.length > 0 ? args.path : "...";
+			text.setText(`${theme.fg("toolTitle", theme.bold("outline"))} ${theme.fg("accent", path)}`);
+			return text;
+		},
+		renderResult(result, { isPartial, expanded }, theme, context) {
+			if (isPartial) return new Text(theme.fg("warning", "Outlining..."), 0, 0);
+			const raw = (result.content?.[0] as { text?: string } | undefined)?.text;
+			if (typeof raw !== "string") return new Text("", 0, 0);
+			if (context.isError) return new Text(theme.fg("error", raw), 0, 0);
+			if (expanded !== true && context.expanded !== true) return new Text("", 0, 0);
+			return new Text(raw, 0, 0);
+		},
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			return withStructuredErrors(signal, {}, () => withAnchorSession(ctx, async () => {
+				const request = normOutlineReq(params, flags.codemode);
+				const rawPath = request.path;
+				const depth = request.depth;
+				const absolutePath = toCwd(rawPath, ctx.cwd);
+
+				abortIf(signal);
+				await valAccess(absolutePath, rawPath);
+
+				abortIf(signal);
+				const file = await loadFileKindAndText(absolutePath, { maxLines: MAX_HASH_LINES, displayPath: rawPath });
+				valKind(file, rawPath);
+				const { normalized, fileHashes, absolutePath: resolvedPath, hadUtf8DecodeErrors } = await readNormFile(
+					rawPath,
+					ctx.cwd,
+					{ signal, preloadedFile: file, maxLines: MAX_HASH_LINES },
+				);
+
+				abortIf(signal);
+				const displayPath = toDisplayPath(ctx.cwd, resolvedPath, rawPath);
+				const fileLines = splitLines(normalized);
+				const section = await buildFileOutline({
+					displayPath,
+					content: normalized,
+					hashes: fileHashes,
+					maxDepth: depth,
+				});
+				serveRows(resolvedPath, fileHashes, fileLines, section.servedHashes);
+
+				const snapshotId = await safeSnapId(absolutePath, "outline");
+				const reclaimNotice = formatAnchorReclaimNotice(takeReclaimedPaths());
+				const notices = [
+					hadUtf8DecodeErrors ? "[Non-UTF-8 bytes shown as U+FFFD; editing rewrites the file as UTF-8.]" : undefined,
+					reclaimNotice,
+				].filter((part): part is string => part !== undefined);
+				const text = [section.text, ...notices].join("\n\n");
+				const served = new Set(section.servedHashes);
+				const structuredContent: OutlineStructured = {
+					ok: true,
+					kind: "outline",
+					path: rawPath,
+					text: section.text,
+					totalLines: normalized.length === 0 ? 0 : fileLines.length,
+					depth,
+					lines: section.rows.filter((row) => served.has(row.anchor)).map((row) => anchoredLine(row.line, row.text, row.anchor)),
+					truncated: section.truncated,
+					complete: section.complete,
+					notices,
+				};
+				const anchorsRequested = request.anchors;
+				const details: OutlineDetails = {
+					truncated: section.truncated,
+					complete: section.complete,
+					snapshotId,
+					metrics: { rows: section.rows.length, truncated: section.truncated },
+				};
+				return {
+					content: [{ type: "text", text }],
+					details,
+					structuredContent: flags.codemode && !anchorsRequested ? text : structuredContent,
+				};
+			}));
+		},
+	});
+}

package/src/prompts.ts

@@ -8,6 +8,7 @@ export interface Guideline {
 
 const GUIDELINE_IDS_BY_NAME: Record<string, readonly string[]> = {
   "read-guidelines.md": ["read-reread", "read-outline", "read-match-served"],
+  "outline-guidelines.md": ["outline-real-lines", "outline-read-span"],
   "replace-guidelines.md": ["replace-disjoint", "replace-deletion", "replace-single-line"],
   "replace-match-guidelines.md": ["replace-match-fragment", "replace-match-wide-range", "replace-match-whole-range"],
   "insert-guidelines.md": ["insert-blank-edges"],

package/src/read.ts

@@ -397,6 +397,7 @@ export function regRead(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FL
 				const notices = [
 					hadUtf8DecodeErrors ? "[Non-UTF-8 bytes shown as U+FFFD; editing rewrites the file as UTF-8.]" : undefined,
 					reclaimNotice,
+					flags.outlineEnabled && preview.truncation !== undefined ? "[Read truncated; call `outline` on this file to see its structure.]" : undefined,
 				].filter((part): part is string => part !== undefined);
 				const previewText = [preview.text, ...notices].join("\n\n");
 				const servedRawText = preview.anchoredLines.map((row) => fileLines[row.line - 1] ?? "").join("\n");

package/src/structured.ts

@@ -82,6 +82,38 @@ export const readResultSchema = Type.Union([
 	structuredErrorSchema,
 ]);
 
+export type OutlineStructured = {
+	ok: true;
+	kind: "outline";
+	path: string;
+	text: string;
+	totalLines: number;
+	depth: number;
+	lines: AnchoredLine[];
+	truncated: boolean;
+	complete: boolean;
+	notices: string[];
+};
+
+export type OutlineResult = OutlineStructured | string | StructuredError;
+
+export const outlineResultSchema = Type.Union([
+	Type.Object({
+		ok: Type.Literal(true),
+		kind: Type.Literal("outline"),
+		path: Type.String(),
+		text: Type.String(),
+		totalLines: Type.Integer(),
+		depth: Type.Integer(),
+		lines: Type.Array(anchoredLineSchema),
+		truncated: Type.Boolean(),
+		complete: Type.Boolean(),
+		notices: Type.Array(Type.String()),
+	}),
+	Type.String(),
+	structuredErrorSchema,
+]);
+
 export type EditVerb = "replaced" | "inserted" | "copied" | "moved" | "undone" | "edited";
 
 export type EditStructured = {

package/tool-prompts/outline-guidelines.md

@@ -0,0 +1,2 @@
+- `outline`: a row shows the first line of the symbol's declaration, and its anchor addresses that line; a `[limit N]` line under it is the span to read.
+- `outline`: read a symbol's span before editing inside its body, because the outline never shows body lines.

package/tool-prompts/outline-snippet.md

@@ -0,0 +1 @@
+Outline one file's structure by anchor: one row per symbol with the first line of its declaration, `[limit N]` for the span of a multi-line symbol

package/tool-prompts/outline.md

@@ -0,0 +1,3 @@
+Return a structural outline of one file: a `=== path (language) — N lines ===` header, then one `anchor│content` row per symbol, where the content is the first line of that symbol's declaration (annotations and attributes excluded). A `[limit N]` line under a multi-line symbol is the span to pass as `read`'s `limit` when reading that symbol's body from its anchor. A `[N nested]` line marks children hidden by `depth`. Files the parser cannot outline fall back to a head-and-tail preview. A row is editable with replace and insert when its line is shown whole; a row whose line is too long is clipped with a trailing `...` and is not served for editing, so read that line first.
+
+The outline is a map, not the file: it shows each symbol's declaration line only, so read the span before editing inside a body. Anchors are lowercase letters and stay valid until their line is edited.

package/tool-prompts/read-guidelines.md

@@ -1,3 +1,3 @@
 - `read`: call again after an edit when you need anchors you lack — post-edit diff `+`/` ` rows and served `anchor│content` rows already carry fresh anchors for the changed range.
-- `read`: an auto-read-all outline row shows a symbol label, or a single-line symbol's content; its `[limit N]` is the span to request.
+- `read`: an auto-read-all outline row is the first line of a symbol's declaration, and a `[limit N]` line under it is the span to request; a row clipped with a trailing `...` is not served for editing.
 - `read`: `replace_match` needs both boundary lines served; copy `match` from a served row or read the lines first.