pi-shorthand 0.12.0 → 0.14.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-shorthand
 
-![A code call in Pi](https://raw.githubusercontent.com/sebinsua/shortsight/main/docs/shorthand.png)
+![A shorthand call in Pi](https://raw.githubusercontent.com/sebinsua/shortsight/main/docs/shorthand.png)
 
 A [Pi](https://github.com/earendil-works/pi) tool for editing repositories with Bun programs, with first-class support for TypeScript and JavaScript.
 
@@ -38,7 +38,9 @@ pi-shorthand gives Pi a programming environment instead of a patch format. This
 
 Programs edit a private workspace, with host files outside the repository kept read-only. Agents are good at improving things a step at a time, so changes are applied a whole file at a time and the agent is told which worked and which didn't. Concurrent edits can cause a run to be rejected; conflict detection is best-effort, not an atomic commit.
 
-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.
+The `shorthand` 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 `shorthand` too. They get back what the run changed as data, not text.
 
 ## Without Pi
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-shorthand",
-	"version": "0.12.0",
+	"version": "0.14.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.12.0"
+		"shorthand-code": "0.14.0"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",

package/src/display.ts

@@ -1,5 +1,5 @@
 /**
- * How a code call looks in Pi. (The model gets a separate plain-text version: see textForModel.)
+ * How a shorthand call looks in Pi. (The model gets a separate plain-text version: see textForModel.)
  *
  * A verdict line first, whose colour carries the outcome. Lines indented under it belong to it: what
  * went wrong, or what to watch out for. A blank line starts a new section. The sections come in the
@@ -38,7 +38,7 @@ export function callLine(
 		args.timeout && `program timeout ${args.timeout}s`,
 	];
 	const suffix = settings.filter(Boolean).join(", ");
-	return `${theme.fg("toolTitle", theme.bold("code"))} ${args.title ?? ""}${suffix ? theme.fg("muted", ` (${suffix})`) : ""}`;
+	return `${theme.fg("toolTitle", theme.bold("shorthand"))} ${args.title ?? ""}${suffix ? theme.fg("muted", ` (${suffix})`) : ""}`;
 }
 
 /** Text to show when a completed tool result has no structured RunResult details. */
@@ -51,7 +51,7 @@ export function unstructuredResultText(content: readonly unknown[]): string {
 		)
 		.join("\n")
 		.trim();
-	return text || "Code failed without result details";
+	return text || "Shorthand failed without result details";
 }
 
 /** Lines that belong to the verdict line above them. */

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * The `code` tool: the model writes one Bun program that makes a multi-step change to the repository.
+ * The `shorthand` tool: the model writes one Bun program that makes a multi-step change to the repository.
  * Its writes go to a copy-on-write overlay; if it succeeds, they're applied and the diff is returned.
  */
 
@@ -22,17 +22,18 @@ 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. Only edits files inside a git repository; use edit or write for anything else. 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 shorthand, 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.
 - await Bun.file(path).text(); await Bun.write(path, text)
 - sg.rewrite(pattern, replacement, files?) discovers and rewrites matching code; omit files for the working directory. $X captures one node; $$$X captures a sequence.
-- sg.one(pattern, files?) selects exactly one match; sg.find returns an array. sg.rewrite also accepts a selected match or array without a file scope.
+- sg.one(pattern, files?) selects exactly one match; sg.find returns an array. sg.rewrite also accepts a selected match or array without a file scope, or a batch of [pattern, replacement] rules applied together to the original code.
 - A rewrite callback receives a match and returns text, a native node.replace(text) edit, or null to skip. Return native edits to apply them. Pass selected arrays together for independent edits; select again after changing their file.
-- await refactor.rename({ file, symbol, to }) renames one resolved TypeScript symbol across the project without changing unrelated names.
-- await refactor.references({ file, symbol }) returns resolved identifier matches that pass straight to sg.rewrite(matches, callback).
+- await refactor.rename({ file, symbol, to }) renames one resolved TypeScript symbol across the project without changing unrelated names; a parameter is named through its function ("load.id"), or give a place with { at: match | { file, line, column }, to }.
+- await refactor.references({ file, symbol } | { at }) returns resolved identifier matches that pass straight to sg.rewrite(matches, callback).
 - await refactor.renameFile({ from, to }) moves a TypeScript file and updates module paths that resolve to it.
+- rename, move and renameFile check the result with TypeScript, refuse what would break it, and return { files }; pass dryRun: true to get { files, diff } and change nothing.
 - 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 five seconds; request more for longer programs. Time spent inside the helpers above does not count toward it, up to 60 extra seconds.`;
@@ -45,12 +46,65 @@ export const SKILLS_DIRECTORY = path.join(
 	"skills",
 );
 
-export function codeDescription(graphAvailable: boolean): string {
+export function shorthandDescription(graphAvailable: boolean): string {
 	return graphAvailable
 		? DESCRIPTION.replace("\n\nSee the shorthand skill", `\n${GRAPH_DESCRIPTION}\nSee the shorthand skill`)
 		: DESCRIPTION;
 }
 
+const paths = (description: string) => Type.Array(Type.String(), { description });
+
+/**
+ * What a script gets back from `shorthand`, 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 SHORTHAND_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 shorthandOutput(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] }));
@@ -59,15 +113,15 @@ export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknow
 	// rather than throwing, since a thrown error loses them.)
 	pi.on("tool_result", async (event) => {
 		const run = event.details as RunResult | undefined;
-		if (event.toolName === "code" && run && runFailed(run)) return { isError: true };
+		if (event.toolName === "shorthand" && run && runFailed(run)) return { isError: true };
 	});
 
 	pi.registerTool({
-		name: "code",
-		label: "Code",
-		description: codeDescription(graphAvailable),
+		name: "shorthand",
+		label: "Shorthand",
+		description: shorthandDescription(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 +144,7 @@ export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknow
 				}),
 			),
 		}),
+		outputSchema: SHORTHAND_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 +177,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 +186,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: shorthandOutput(result),
 			};
 		},
 
@@ -142,12 +199,12 @@ export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknow
 		},
 
 		renderResult(result, options, theme) {
-			return renderCodeResult(result, options, theme);
+			return renderShorthandResult(result, options, theme);
 		},
 	});
 }
 
-export function renderCodeResult(
+export function renderShorthandResult(
 	result: { content: readonly unknown[]; details?: unknown },
 	{ expanded, isPartial }: { expanded: boolean; isPartial: boolean },
 	theme: Theme,