pi-pwsh-native 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project will be documented here.
 
+## 0.1.3 — 2026-08-01
+
+### Fixed
+
+- Respect the final PowerShell command's success state instead of allowing a stale native `$LASTEXITCODE` to override it.
+
+### Changed
+
+- Reduced recurring model prompt overhead by shortening the shell description and consolidating PowerShell guidance.
+- Deferred PowerShell runtime probing until a session starts, avoiding unnecessary subprocesses in Pi invocations that only load extensions.
+- Declared the supported Pi and Node.js version ranges explicitly.
+- Added minimum/latest Pi compatibility coverage and prompt-budget regression tests.
+
+## 0.1.2 — 2026-07-30
+
+### Added
+
+- `pi` npm keyword for broader package-gallery discoverability.
+- README comparison with the audited `@4fu/pi-pwsh@0.6.2` baseline.
+
 ## 0.1.1 — 2026-07-30
 
 ### Added

package/README.md

@@ -7,6 +7,29 @@ Native PowerShell 7 tooling for the [Pi coding agent](https://pi.dev/) on Window
 
 `pi-pwsh-native` replaces Pi's model-callable `bash` tool with a tool named `pwsh` and routes interactive `!`/`!!` commands through the same verified PowerShell executable. It does not translate Bash syntax and does not silently fall back to another shell.
 
+![PowerShell 7 preview](https://raw.githubusercontent.com/takomine/pi-pwsh-native/main/public/img.png)
+
+## How this differs from `@4fu/pi-pwsh`
+
+This package derives from [`@4fu/pi-pwsh`](https://github.com/4fuu/pi-pwsh), but it is a deliberately leaner shell replacement rather than a drop-in feature superset. The comparison below is against the audited upstream baseline, `@4fu/pi-pwsh@0.6.2`.
+
+| Area | `pi-pwsh-native` | `@4fu/pi-pwsh@0.6.2` |
+|---|---|---|
+| Primary focus | Predictable, dependency-free foreground PowerShell execution | Feature-rich PowerShell execution with persistent jobs and interactive sessions |
+| Model shell tool | Replaces `bash` with `pwsh` | Replaces `bash` with `pwsh` |
+| Pi discovery tools | Preserves `ls`, `find`, and `grep` by default | Disables `ls`, `find`, and `grep` in favor of PowerShell |
+| Interactive `!` / `!!` | Routes both through the verified PowerShell runtime | Does not replace Pi's `user_bash` handling |
+| PowerShell executable | Resolves, verifies, and retains an absolute PowerShell 7 path | Probes PowerShell 7, while foreground execution invokes `pwsh` by name |
+| Execution policy | No override by default; `Bypass` must be explicitly configured | Passes `-ExecutionPolicy Bypass` |
+| Command transport | UTF-8 base64 source over stdin, avoiding Windows command-line limits | Injected source passed through `-Command` |
+| `.cmd` fallback | No retry through `cmd.exe` | Can retry failed direct command-shim execution through `cmd /c` |
+| Background jobs and PTYs | Intentionally omitted from the lean core | Includes detached jobs, ConPTY sessions, and user-request helpers |
+| Runtime dependencies | None | Uses `node-pty` and `@xterm/headless` |
+| Configuration | Strict JSON configuration plus environment overrides | Primarily opinionated built-in behavior |
+| Missing/invalid PowerShell | Fails visibly without silently restoring Bash | Leaves the built-in Bash tool active when PowerShell is unavailable |
+
+Choose `pi-pwsh-native` when you want a small, auditable PowerShell 7 replacement with dedicated Pi file/search tools left intact. Choose `@4fu/pi-pwsh` when persistent background jobs, PTYs, and its interactive helper layer are more important. Do not enable competing shell-adapter extensions simultaneously.
+
 ## Design
 
 - Registers a real `pwsh` tool so models are prompted to write PowerShell, not POSIX shell syntax.
@@ -24,7 +47,8 @@ Native PowerShell 7 tooling for the [Pi coding agent](https://pi.dev/) on Window
 
 - Windows
 - PowerShell 7+
-- Pi with extension support
+- Node.js 22.19 or newer
+- Pi 0.83.0 or newer (before 1.0)
 
 The initial implementation is developed and tested against:
 
@@ -36,7 +60,7 @@ The initial implementation is developed and tested against:
 Install the pinned npm release:
 
 ```powershell
-pi install npm:pi-pwsh-native@0.1.1
+pi install npm:pi-pwsh-native@0.1.3
 ```
 
 Alternatively, install the public GitHub package directly:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pwsh-native",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Native PowerShell 7 tooling for the Pi coding agent on Windows",
   "license": "MIT",
   "author": "Tako (https://github.com/takomine)",
@@ -20,10 +20,11 @@
     "win32"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.19.0"
   },
   "keywords": [
     "pi-package",
+    "pi",
     "pi-extension",
     "powershell",
     "pwsh",
@@ -54,7 +55,7 @@
     "smoke": "npm run test:runtime && npm run test:exitcode && npm run test:timeout"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": ">=0.83.0 <1.0.0"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.83.0",

package/src/index.ts

@@ -27,11 +27,17 @@ export function selectActiveTools(
 	return [...new Set(selected)];
 }
 
-function toolDescription(runtime: PowerShellRuntime, config: PwshNativeConfig): string {
-	const elevation = config.elevationGuidance
-		? " Elevation guidance is enabled, but elevate only after an explicit user request."
-		: " Do not elevate unless the user explicitly requests it.";
-	return `Execute a native PowerShell 7 command on Windows with PowerShell ${runtime.version} (${runtime.executable}). Returns stdout and stderr. Output is truncated to the last 2000 lines or 50KB, whichever is reached first; full truncated output is saved to a temporary file. Commands have no default timeout; set timeout in seconds when needed.${elevation}`;
+export const PWSH_TOOL_DESCRIPTION =
+	"Execute native PowerShell 7 on Windows. Output is tail-truncated to 2,000 lines or 50 KB; full output is saved to a temporary file. Optional timeout is in seconds.";
+
+export function createPromptGuidelines(config: PwshNativeConfig): string[] {
+	return [
+		"Use pwsh only when a shell is needed; use native PowerShell syntax and $env:NAME for environment variables.",
+		"Prefer dedicated file and search tools over pwsh; otherwise bound recursive output and prefer rg or fd when available.",
+		config.elevationGuidance
+			? "In pwsh, elevation guidance is enabled, but elevate only after an explicit user request."
+			: "Do not elevate from pwsh unless the user explicitly requests it.",
+	];
 }
 
 function unavailableUserCommand(reason: string) {
@@ -55,51 +61,51 @@ export default function piPwshNative(pi: ExtensionAPI): void {
 
 	let config: PwshNativeConfig | undefined;
 	let runtime: PowerShellRuntime | undefined;
+	let operations: ReturnType<typeof createPowerShellOperations> | undefined;
 	let setupError: string | undefined;
 	try {
 		config = loadConfig({ agentDir: getAgentDir() }).config;
-		runtime = resolvePowerShellRuntime(config);
 	} catch (error) {
 		setupError = errorMessage(error);
 	}
 
-	if (setupError || !config || !runtime) {
-		const reason = setupError ?? "unknown setup failure";
-		pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", (_event, ctx) => {
+		if (!setupError && config && !runtime) {
+			try {
+				runtime = resolvePowerShellRuntime(config);
+				operations = createPowerShellOperations(runtime, config);
+			} catch (error) {
+				setupError = errorMessage(error);
+			}
+		}
+
+		if (setupError || !config || !runtime || !operations) {
+			const reason = setupError ?? "unknown setup failure";
 			pi.setActiveTools(selectActiveTools(pi.getActiveTools(), true, false));
 			ctx.ui.notify(`pi-pwsh-native: ${reason} Bash was disabled; no shell fallback was activated.`, "error");
-		});
-		pi.on("user_bash", () => unavailableUserCommand(reason));
-		return;
-	}
-
-	const resolvedConfig = config;
-	const resolvedRuntime = runtime;
-	const operations = createPowerShellOperations(resolvedRuntime, resolvedConfig);
+			return;
+		}
 
-	pi.on("session_start", (_event, ctx) => {
 		const definition = createBashToolDefinition(ctx.cwd, { operations });
 		pi.registerTool({
 			...definition,
 			name: "pwsh",
 			label: "pwsh",
-			description: toolDescription(resolvedRuntime, resolvedConfig),
-			promptSnippet: "Execute native PowerShell 7 commands on Windows",
-			promptGuidelines: [
-				"Use pwsh only when a shell is needed; write native PowerShell syntax and avoid Bash-only syntax or implicit Bash translation.",
-				"Prefer read, write, edit, ls, find, and grep over pwsh when a dedicated tool can complete the task more directly.",
-				"In pwsh, use $env:NAME for environment variables; single quotes are literal, double quotes interpolate, and the backtick is the escape character.",
-				"Prefer bounded rg or fd commands for repository search; tightly bound recursive Get-ChildItem and Select-String operations.",
-				"Do not elevate pwsh commands unless the user explicitly requests elevation.",
-				"Inspect PI_* environment variables in pwsh when current Pi model or session metadata is needed.",
-			],
+			description: PWSH_TOOL_DESCRIPTION,
+			promptSnippet: "Execute native PowerShell 7 commands",
+			promptGuidelines: createPromptGuidelines(config),
 		});
 		pi.setActiveTools(
-			selectActiveTools(pi.getActiveTools(), resolvedConfig.preserveDiscoveryTools, true),
+			selectActiveTools(pi.getActiveTools(), config.preserveDiscoveryTools, true),
 		);
 	});
 
-	if (resolvedConfig.replaceUserBash) {
-		pi.on("user_bash", () => ({ operations }));
+	const replaceUserBash = config?.replaceUserBash ?? true;
+	if (replaceUserBash) {
+		pi.on("user_bash", () =>
+			operations
+				? { operations }
+				: unavailableUserCommand(setupError ?? "PowerShell has not been initialized"),
+		);
 	}
 }

package/src/powershell-source.ts

@@ -10,15 +10,16 @@ export const UTF8_PREFIX = [
 ].join("; ") + "; ";
 
 /**
- * Preserve a native program's real exit code. If no native program set
- * LASTEXITCODE, map PowerShell's success state to 0/1.
+ * Report the final command's status. A successful final command wins over a
+ * stale LASTEXITCODE; a failed final native command retains its real code;
+ * other PowerShell failures map to 1.
  *
  * The leading newline detaches the epilogue from a trailing line comment. The
  * leading semicolon also prevents a trailing backtick from joining the
  * epilogue to the user's final command.
  */
 export const EXIT_EPILOGUE =
-	"\n; $__pi_ok = $?; if ($null -ne $global:LASTEXITCODE) { exit $global:LASTEXITCODE } else { exit ($__pi_ok ? 0 : 1) }";
+	"\n; $__pi_ok = $?; if ($__pi_ok) { exit 0 } elseif ($null -ne $global:LASTEXITCODE -and $global:LASTEXITCODE -ne 0) { exit $global:LASTEXITCODE } else { exit 1 }";
 
 export function buildPowerShellSource(command: string, config: PwshNativeConfig): string {
 	const strict = config.strictMode ? "$ErrorActionPreference = 'Stop'; " : "";