pi-shorthand 0.11.0 → 0.13.0

package/README.md

@@ -40,6 +40,8 @@ Programs edit a private workspace, with host files outside the repository kept r
 
 The `code` tool uses Pi's working directory by default. Pass `cwd` to target another checkout; relative paths are resolved from Pi's working directory. For example, when Pi starts in a bare worktree container, `cwd: "child"` targets its `child` worktree. The chosen directory must be inside a Git worktree.
 
+Scripts run by Pi's `codemode` tool can call `code` too. They get back what the run changed as data, not text.
+
 ## Without Pi
 
 The engine is published separately as [shorthand-code](https://github.com/sebinsua/shortsight/tree/main/packages/shorthand-code), with a `shorthand` command that runs a program from a file or stdin and prints the same result. See `shorthand --help`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-shorthand",
-	"version": "0.11.0",
+	"version": "0.13.0",
 	"description": "Pi tool for editing repositories with Bun programs, with first-class support for TypeScript and JavaScript.",
 	"keywords": [
 		"ast-grep",
@@ -26,7 +26,7 @@
 	],
 	"type": "module",
 	"dependencies": {
-		"shorthand-code": "0.11.0"
+		"shorthand-code": "0.13.0"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",

package/src/display.ts

@@ -25,8 +25,7 @@ const ANSI_CUBE_VALUES = [0, 95, 135, 175, 215, 255];
 const ANSI_GRAY_VALUES = Array.from({ length: 24 }, (_, index) => 8 + index * 10);
 
 const OUTPUT_PREVIEW_LINES = 5; // like Pi's bash tool
-const INLINE_DIFF_LINES = 40; // a longer diff collapses to a list of its files…
-const LISTED_FILES = 8; // …showing this many, then "and N more files"
+const LISTED_FILES = 8; // a diff too tall for the screen lists this many files, then "and N more files"
 const EXPANDED_DIFF_LINES = 2000; // even expanded, a diff of hundreds of files stops here
 
 export function callLine(
@@ -60,7 +59,8 @@ function indent(line: string): string {
 	return `  ${line}`;
 }
 
-export function resultLines(run: RunResult, expanded: boolean, theme: Theme): string[] {
+/** `collapseDiff` swaps the applied diff for a list of its files; see FitsScreen for when. */
+export function resultLines(run: RunResult, expanded: boolean, theme: Theme, collapseDiff = false): string[] {
 	const applied = run.changes.filter((change) => run.applied.includes(change.path));
 	const notApplied = run.changes.filter(
 		(change) => !run.applied.includes(change.path) && !run.rolledBack.includes(change.path),
@@ -95,7 +95,7 @@ export function resultLines(run: RunResult, expanded: boolean, theme: Theme): st
 	const sections: string[][] = [];
 	const background: ToolBackground =
 		run.exitCode === 0 && run.conflicts.length === 0 && run.rolledBack.length === 0 ? "toolSuccessBg" : "toolErrorBg";
-	if (applied.length > 0) sections.push(diffLines(applied, expanded, theme, background));
+	if (applied.length > 0) sections.push(diffLines(applied, collapseDiff && !expanded, theme, background));
 	if (output && (expanded || !error)) sections.push(outputLines(output, expanded, run.changes.length > 0, theme));
 	if (notApplied.length > 0) sections.push(notAppliedLines(notApplied, expanded, theme, background));
 	for (const section of sections) lines.push("", ...section);
@@ -157,14 +157,12 @@ function outputLines(output: string, expanded: boolean, labelled: boolean, theme
 	return [...label, hint, ...lines.slice(-OUTPUT_PREVIEW_LINES)];
 }
 
-/** Each file's diff under its name, in Pi's own diff style. A long diff collapses to a list of files. */
-function diffLines(changes: FileChange[], expanded: boolean, theme: Theme, background: ToolBackground): string[] {
-	const files = changes.map((change) => [fileLine(change, theme), ...renderFileDiff(change, theme, background)]);
-	const total = files.reduce((sum, file) => sum + file.length, 0);
-	if (!expanded && total > INLINE_DIFF_LINES) {
+/** Each file's diff under its name, in Pi's own diff style, or when collapsed a list of the files. */
+function diffLines(changes: FileChange[], collapse: boolean, theme: Theme, background: ToolBackground): string[] {
+	if (collapse) {
 		return [...fileList(changes, theme), theme.fg("muted", `(${keyHint("app.tools.expand", "to see the diff")})`)];
 	}
-
+	const files = changes.map((change) => [fileLine(change, theme), ...renderFileDiff(change, theme, background)]);
 	const lines = files.flatMap((file, index) => (index === 0 ? file : ["", ...file]));
 	if (lines.length <= EXPANDED_DIFF_LINES) return lines;
 	const more = lines.length - EXPANDED_DIFF_LINES;
@@ -316,7 +314,7 @@ function colorDistance(first: number[], second: number[]): number {
 
 function notAppliedLines(changes: FileChange[], expanded: boolean, theme: Theme, background: ToolBackground): string[] {
 	const heading = theme.fg("muted", `Would have changed ${fileCount(changes)} · `) + stats(changes, theme);
-	if (expanded) return [heading, "", ...diffLines(changes, true, theme, background)];
+	if (expanded) return [heading, "", ...diffLines(changes, false, theme, background)];
 	return [heading + theme.fg("muted", ` (${keyHint("app.tools.expand", "to see the diff")})`)];
 }
 

package/src/index.ts

@@ -7,7 +7,7 @@ import { createRequire } from "node:module";
 import * as path from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { type ExtensionAPI, type Theme, truncateHead, truncateTail } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import { type Component, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import {
 	DEFAULT_TIMEOUT_SECONDS,
@@ -22,7 +22,7 @@ import {
 } from "shorthand-code";
 import { callLine, resultLines, unstructuredResultText } from "./display.ts";
 
-const DESCRIPTION = `Edit repository files with a TypeScript program run by Bun. Best for changes across many files, repeated edits and semantic TypeScript renames or moves; a small change to one file is quicker as a direct edit. Top-level await and ordinary Bun/Node APIs work. Use repository-relative paths. Set cwd to a checkout path when Pi's working directory is outside the repository, such as a child worktree in a bare worktree container. The program runs in an isolated workspace; changes apply on successful exit by default and the tool reports the diff. Run tests, type-checks and builds separately afterward with the shell tool.
+const DESCRIPTION = `Edit repository files with a TypeScript program run by Bun. Best for changes across many files, repeated edits and semantic TypeScript renames or moves; a small change to one file is quicker as a direct edit. Top-level await and ordinary Bun/Node APIs work. Use repository-relative paths. Set cwd to a checkout path when Pi's working directory is outside the repository, such as a child worktree in a bare worktree container. The program runs in an isolated workspace; changes apply on successful exit by default and the tool reports the diff. Tests, type-checks and builds belong outside the program: in a shell call, or, when a codemode script calls code, later in that script.
 
 Common operations:
 - edit({ path, oldText, newText }) replaces exactly one literal occurrence; missing or ambiguous text is an error. Use text edits for known source, structural matching when it saves enumerating occurrences or preserves varying syntax.
@@ -35,7 +35,7 @@ Common operations:
 - await refactor.renameFile({ from, to }) moves a TypeScript file and updates module paths that resolve to it.
 - await refactor.move({ file, symbol, to }) moves a top-level declaration to another file and updates the imports that follow it.
 
-See the shorthand skill for renames, moves and call-site migrations. Read its advanced-refactors.md guide only to extract code, move syntax or use rule objects. The default timeout is two seconds; request more for longer programs. Time spent inside the helpers above does not count toward it, up to 60 extra seconds.`;
+See the shorthand skill for renames, moves and call-site migrations. Read its advanced-refactors.md guide only to extract code, move syntax or use rule objects. The default timeout is five seconds; request more for longer programs. Time spent inside the helpers above does not count toward it, up to 60 extra seconds.`;
 
 const GRAPH_DESCRIPTION =
 	"- await graph.query(request | request[]) queries symbols and relationships; graph results can be passed to sg as scope. The graph shows the repository before this program's edits.\n";
@@ -51,6 +51,59 @@ export function codeDescription(graphAvailable: boolean): string {
 		: DESCRIPTION;
 }
 
+const paths = (description: string) => Type.Array(Type.String(), { description });
+
+/**
+ * What a script gets back from `code`, for example one run by Pi's codemode tool. The model still sees the text.
+ * A failed run resolves to this too, so a script checks `exitCode`.
+ */
+export const CODE_OUTPUT_SCHEMA = Type.Object({
+	exitCode: Type.Optional(
+		Type.Union([Type.Number(), Type.Null()], { description: "0 on success; null when the program was killed" }),
+	),
+	timedOut: Type.Optional(Type.Boolean()),
+	output: Type.Optional(Type.String({ description: "The program's stdout and stderr" })),
+	errorLine: Type.Optional(Type.String({ description: "On failure, the program line the error came from" })),
+	warnings: Type.Optional(Type.Array(Type.String(), { description: "Likely mistakes spotted before it ran" })),
+	changes: Type.Optional(
+		Type.Array(
+			Type.Object({
+				path: Type.String(),
+				kind: StringEnum(["added", "modified", "deleted"] as const),
+				patch: Type.String(),
+			}),
+		),
+	),
+	applied: Type.Optional(paths("Changed files written to the repository")),
+	conflicts: Type.Optional(paths("Files that changed outside the run while it ran; if any, nothing was applied")),
+	rolledBack: Type.Optional(paths("Changed files not kept after a failure")),
+	infrastructureError: Type.Optional(Type.String({ description: "Set, alone, when the program couldn't be run" })),
+});
+
+export function codeOutput(result: RunResult) {
+	const { exitCode, timedOut, output, errorLine, warnings, applied, conflicts, rolledBack } = result;
+	const changes = result.changes.map((change) => ({ path: change.path, kind: change.kind, patch: change.patch }));
+	return {
+		exitCode,
+		timedOut,
+		output,
+		...(errorLine === undefined ? {} : { errorLine }),
+		warnings,
+		changes,
+		applied,
+		conflicts,
+		rolledBack,
+	};
+}
+
+/**
+ * Base name of the temporary files that hold a large run's full diff or output. A call a codemode script makes has
+ * an id like `<parent id>/1`, and ids can hold `|`, so anything but a safe file-name character is replaced.
+ */
+export function spillName(toolCallId: string): string {
+	return `pi-shorthand-${toolCallId.replace(/[^\w.-]/g, "_")}`;
+}
+
 export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknown> = sightreadAvailable) {
 	// The shorthand skill ships with shorthand-code, whose `shorthand --skill` prints it for other agents.
 	pi.on("resources_discover", () => ({ skillPaths: [SKILLS_DIRECTORY] }));
@@ -67,7 +120,7 @@ export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknow
 		label: "Code",
 		description: codeDescription(graphAvailable),
 		promptSnippet:
-			"Make multi-file, repetitive or rename/move changes with one Bun program; a small change to one file is quicker as a direct edit. Run verification separately afterward",
+			"Make multi-file, repetitive or rename/move changes with one Bun program; a small change to one file is quicker as a direct edit. Keep verification outside the program",
 
 		parameters: Type.Object({
 			title: Type.String({ description: "A few words describing the change, shown to the user" }),
@@ -90,6 +143,7 @@ export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknow
 				}),
 			),
 		}),
+		outputSchema: CODE_OUTPUT_SCHEMA,
 
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			// While it runs, show how long it's been going and the latest reported step.
@@ -122,6 +176,7 @@ export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknow
 					isError: true,
 					content: [{ type: "text" as const, text: [error.message, ...diagnosticLines(error.diagnostics)].join("\n") }],
 					details: { infrastructureError: error.message, diagnostics: error.diagnostics },
+					structuredContent: { infrastructureError: error.message },
 				};
 			} finally {
 				clearInterval(progress);
@@ -130,10 +185,11 @@ export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknow
 				content: [
 					{
 						type: "text",
-						text: textForModel(result, { name: `pi-shorthand-${toolCallId}`, truncateHead, truncateTail }),
+						text: textForModel(result, { name: spillName(toolCallId), truncateHead, truncateTail }),
 					},
 				],
 				details: result,
+				structuredContent: codeOutput(result),
 			};
 		},
 
@@ -151,7 +207,7 @@ export function renderCodeResult(
 	result: { content: readonly unknown[]; details?: unknown },
 	{ expanded, isPartial }: { expanded: boolean; isPartial: boolean },
 	theme: Theme,
-): Text {
+): Component {
 	if (isPartial) {
 		const progress = (result.details as { progress?: string } | undefined)?.progress;
 		return new Text(theme.fg("muted", progress ? `running… ${progress}` : "running…"), 0, 0);
@@ -170,5 +226,32 @@ export function renderCodeResult(
 	}
 	const run = result.details as RunResult | undefined;
 	if (!run) return new Text(theme.fg("error", unstructuredResultText(result.content)), 0, 0);
-	return new Text(resultLines(run, expanded, theme).join("\n"), 0, 0);
+	const full = new Text(resultLines(run, expanded, theme).join("\n"), 0, 0);
+	if (expanded) return full;
+	return new FitsScreen(full, new Text(resultLines(run, false, theme, true).join("\n"), 0, 0));
+}
+
+/** Rows Pi keeps for itself below a tool result: the editor, its borders and the footer. */
+const PI_CHROME_ROWS = 8;
+
+/**
+ * Shows the whole result while it fits on screen once wrapped, like Pi's edit tool, and otherwise the version
+ * with the diff collapsed to a list of files. Measured on each render, so resizing the terminal is followed.
+ */
+export class FitsScreen implements Component {
+	constructor(
+		private readonly full: Component,
+		private readonly collapsed: Component,
+		private readonly rows = () => process.stdout.rows || 24,
+	) {}
+
+	render(width: number): string[] {
+		const lines = this.full.render(width);
+		return lines.length <= this.rows() - PI_CHROME_ROWS ? lines : this.collapsed.render(width);
+	}
+
+	invalidate(): void {
+		this.full.invalidate();
+		this.collapsed.invalidate();
+	}
 }