pi-shorthand 0.13.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,9 +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 `code` too. They get back what the run changed as data, not text.
+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.13.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.13.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. Tests, type-checks and builds belong outside the program: in a shell call, or, when a codemode script calls code, later in that script.
+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,7 +46,7 @@ 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;
@@ -54,10 +55,10 @@ export function codeDescription(graphAvailable: boolean): string {
 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.
+ * 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 CODE_OUTPUT_SCHEMA = Type.Object({
+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" }),
 	),
@@ -80,7 +81,7 @@ export const CODE_OUTPUT_SCHEMA = Type.Object({
 	infrastructureError: Type.Optional(Type.String({ description: "Set, alone, when the program couldn't be run" })),
 });
 
-export function codeOutput(result: RunResult) {
+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 {
@@ -112,13 +113,13 @@ 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. Keep verification outside the program",
 
@@ -143,7 +144,7 @@ export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknow
 				}),
 			),
 		}),
-		outputSchema: CODE_OUTPUT_SCHEMA,
+		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.
@@ -189,7 +190,7 @@ export default async function (pi: ExtensionAPI, findGraph: () => Promise<unknow
 					},
 				],
 				details: result,
-				structuredContent: codeOutput(result),
+				structuredContent: shorthandOutput(result),
 			};
 		},
 
@@ -198,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,