@bacnh85/pi-windows-tools 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# pi-windows-tools
+
+Pi extension for Windows-native tool manipulation — shell profiles, path conversion, command execution, WSL bridge, safety policy, and developer tool discovery.
+
+## Installation
+
+```bash
+npm install @bacnh85/pi-windows-tools
+```
+
+## Configuration
+
+```json
+{
+  "extensions": ["pi-windows-tools"],
+  "windowsTools": {
+    "enabled": true,
+    "defaultShell": "pwsh",
+    "allowShellFallback": true,
+    "gitBashPath": null,
+    "wslDistro": null,
+    "preferWslFor": ["openwrt", "yocto", "linux-kernel", "embedded-linux"]
+  }
+}
+```
+
+Environment overrides:
+
+```
+PI_WINDOWS_TOOLS_ENABLED=true
+PI_WINDOWS_SHELL=pwsh|powershell|cmd|git-bash|wsl
+PI_GIT_BASH_PATH=C:\Program Files\Git\bin\bash.exe
+PI_WSL_DISTRO=Ubuntu-24.04
+```
+
+## Commands
+
+- `pi windows doctor` — detect installed developer tools and system state
+- `pi windows shell [shell]` — set default shell (pwsh/powershell/cmd/git-bash/wsl)
+
+## Shell priority
+
+1. pwsh (PowerShell 7+)
+2. powershell (Windows PowerShell 5.1)
+3. Git Bash
+4. cmd
+5. WSL (only when explicitly requested or project config prefers it)

package/docs/windows-tools.md

@@ -0,0 +1,191 @@
+# pi-windows-tools
+
+## Overview
+
+`pi-windows-tools` is a Pi extension that gives the Pi Coding Agent excellent Windows-native tool manipulation capability — shell profiles, path conversion, command execution, WSL bridge, safety policy, and developer tool discovery.
+
+## Installation
+
+```bash
+npm install @bacnh85/pi-windows-tools
+```
+
+Then add to your Pi configuration:
+
+```json
+{
+  "extensions": ["pi-windows-tools"]
+}
+```
+
+## Quick Start
+
+After installation, Pi automatically detects your Windows shell environment and injects PowerShell syntax guidance. Run the doctor to see what's available:
+
+```
+pi windows doctor
+```
+
+## Configuration
+
+```json
+{
+  "windowsTools": {
+    "enabled": true,
+    "defaultShell": "pwsh",
+    "allowShellFallback": true,
+    "gitBashPath": null,
+    "wslDistro": null,
+    "preferWslFor": [
+      "openwrt",
+      "yocto",
+      "linux-kernel",
+      "embedded-linux"
+    ]
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PI_WINDOWS_TOOLS_ENABLED` | Set to `false` to disable (`true` by default) |
+| `PI_WINDOWS_SHELL` | Override default shell: `pwsh`, `powershell`, `cmd`, `git-bash`, `wsl` |
+| `PI_GIT_BASH_PATH` | Explicit path to Git Bash executable |
+| `PI_WSL_DISTRO` | Default WSL distro name |
+
+## Shell Selection
+
+### Priority Order
+
+1. **pwsh** (PowerShell 7+) — preferred, best developer experience
+2. **powershell** (Windows PowerShell 5.1) — built-in, widely available
+3. **git-bash** (Git for Windows Bash) — POSIX commands on Windows
+4. **cmd** (Command Prompt) — legacy, minimal capability
+5. **wsl** (WSL2) — only when explicitly selected or project config prefers it
+
+### Changing Shell
+
+```
+pi windows shell pwsh
+pi windows shell git-bash
+pi windows shell wsl
+```
+
+## Commands
+
+### `pi windows doctor`
+
+Detects installed developer tools and system configuration:
+
+```
+Windows Tools Doctor
+━━━━━━━━━━━━━━━━━━━
+OS: Windows_NT 10.0.22631
+Architecture: x64
+Default shell: pwsh
+
+── Tools ──
+  ✓ pwsh 7.4.0
+  ✓ powershell 5.1.22621
+  ✓ cmd
+  ✓ git 2.42.0.windows.2
+  ✓ bash (Git Bash) 5.2.15
+  ✓ wsl
+  ✓ node v22.0.0
+  ✓ npm 10.5.0
+  ✗ pnpm
+  ...
+
+── WSL Distros ──
+  • Ubuntu-24.04
+  • Debian
+
+── System Features ──
+  Long paths: enabled
+  Developer Mode: enabled
+```
+
+### `pi windows shell [shell]`
+
+Show or set the default Windows shell.
+
+## Tools
+
+The extension registers these tools:
+
+| Tool | Description |
+|------|-------------|
+| `windows_shell_detect` | Detect available shells with versions |
+| `windows_shell_exec` | Execute command through a shell |
+| `windows_path_to_windows` | Convert POSIX/WSL path to Windows format |
+| `windows_path_to_wsl` | Convert Windows path to WSL `/mnt/c/...` |
+| `windows_path_to_gitbash` | Convert Windows path to Git Bash `/c/...` |
+| `windows_path_quote` | Quote a path for a specific shell |
+| `windows_safety_classify` | Check command for dangerous patterns |
+| `windows_doctor` | Full doctor report |
+| `windows_wsl_exec` | Execute command inside WSL |
+| `windows_tool_discover` | Check if a tool is in PATH |
+| `windows_wsl_list_distros` | List installed WSL distros |
+
+## Safety Policy
+
+Commands matching dangerous patterns (rm -rf, diskpart, format, git push --force, npm publish, etc.) are classified as requiring confirmation. Sensitive file paths (.env, .pem, .ssh, .aws, etc.) trigger the same behavior.
+
+## Path Conversion Examples
+
+| Windows | Git Bash | WSL |
+|---------|----------|-----|
+| `C:\Users\bacnh\project` | `/c/Users/bacnh/project` | `/mnt/c/Users/bacnh/project` |
+| `D:\work\repo` | `/d/work/repo` | `/mnt/d/work/repo` |
+| `C:\Program Files\Git` | `/c/Program Files/Git` | `/mnt/c/Program Files/Git` |
+
+## Recommended Setup
+
+1. Install [PowerShell 7](https://github.com/PowerShell/PowerShell) (recommended)
+2. Install [Git for Windows](https://git-scm.com/download/win) (includes Git Bash)
+3. Install [Windows Terminal](https://learn.microsoft.com/en-us/windows/terminal/install) (optional, better UX)
+4. Optional: Install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) with Ubuntu
+
+## Project-Specific Config
+
+For Linux-native projects (OpenWrt, Yocto, kernel builds):
+
+```json
+{
+  "windowsTools": {
+    "defaultShell": "wsl",
+    "wslDistro": "Ubuntu-24.04",
+    "preferWslFor": ["openwrt", "yocto", "linux-kernel"]
+  }
+}
+```
+
+## Common Syntax Mistakes
+
+When using PowerShell (default), these commands **don't work**:
+
+```
+❌ NODE_ENV=test npm test     → ✅ $env:NODE_ENV = "test"; npm test
+❌ rm -rf dist                → ✅ Remove-Item -Recurse -Force .\dist
+❌ cp README.md dist/         → ✅ Copy-Item .\README.md .\dist\
+❌ grep -R "abc" src/         → ✅ Select-String -Path .\src\* -Pattern "abc"
+❌ export FOO=bar             → ✅ $env:FOO = "bar"
+```
+
+When using Git Bash, POSIX commands work but paths need conversion:
+
+```
+# Git Bash: use /c/... instead of C:\...
+cd /c/Users/bacnh/project
+ls -la
+```
+
+When using WSL, always use `/mnt/c/...` for Windows paths:
+
+```
+# WSL: Windows C: drive is at /mnt/c/
+cd /mnt/c/Users/bacnh/project
+make
+```

package/extensions/index.ts

@@ -0,0 +1,96 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { detectShell, detectAllShells, getDefaultShell } from "./lib/shell-detect";
+import type { WindowsShellKind } from "./lib/shell-detect";
+import { executeCommand as execCmd } from "./lib/shell-exec";
+import * as pathUtils from "./lib/path-utils";
+import { classifyCommand } from "./lib/safety";
+import { runDoctor, formatDoctorReport } from "./lib/doctor";
+import { buildShellGuidance } from "./lib/prompts";
+import { execFileSync } from "node:child_process";
+
+const sk = Type.Union([Type.Literal("pwsh"), Type.Literal("powershell"), Type.Literal("cmd"), Type.Literal("git-bash"), Type.Literal("wsl")]);
+const tp = Type.Optional(Type.Number({ description: "Timeout in ms." }));
+const cs = { timeout_ms: tp };
+const EOL = "\n";
+
+function tr(text: string) { return Promise.resolve({ content: [{ type: "text" as const, text }], details: {} }); }
+function rs(shell?: WindowsShellKind): WindowsShellKind {
+	if (shell) return shell;
+	const e = process.env.PI_WINDOWS_SHELL as WindowsShellKind | undefined;
+	if (e && ["pwsh", "powershell", "cmd", "git-bash", "wsl"].includes(e)) return e;
+	return getDefaultShell().kind;
+}
+
+// ponytail: in-memory audit log, no cap, sequence-counter instead of timestamps
+const _log: { shell: string; command: string; exitCode: number | null; timedOut: boolean }[] = [];
+function _fmt() {
+	if (!_log.length) return "No commands executed yet.";
+	return _log.map((e, i) => {
+		const tag = e.timedOut ? " [TIMED OUT]" : "";
+		const cmd = e.command.length > 300 ? e.command.slice(0, 300) + "…" : e.command;
+		return `[${i + 1}] ${e.shell}  exit:${e.exitCode}${tag}\n    cmd: ${cmd}`;
+	}).join(EOL + EOL);
+}
+
+export default function piWindowsToolsExtension(pi: ExtensionAPI) {
+	pi.registerTool({ name: "windows_shell_detect", label: "Windows: Detect Shells", description: "Detect available Windows shells.", promptSnippet: "Detect available Windows shells", promptGuidelines: ["Use to check what shells are available."], parameters: Type.Object({ ...cs }),
+		execute() { return tr(detectAllShells().map(s => `  ${s.available ? "✓" : "✗"} ${s.displayName}${s.version ? ` ${s.version}` : ""}`).join(EOL)); } });
+
+	pi.registerTool({ name: "windows_shell_exec", label: "Windows: Execute Command", description: "Execute a command through a Windows shell.", promptSnippet: "Execute a command through a Windows shell",
+		promptGuidelines: ["Use instead of generic bash on Windows.", 'Use shell:"wsl" for WSL.', "Dangerous commands require confirmation."],
+		parameters: Type.Object({ command: Type.String(), shell: Type.Optional(sk), cwd: Type.Optional(Type.String()), timeout_ms: tp }),
+		async execute(_id, p, _s, _u, ctx) {
+			const opts = { shell: rs(p.shell as WindowsShellKind | undefined), cwd: p.cwd || ctx?.cwd || process.cwd(), timeoutMs: p.timeout_ms };
+			const safe = classifyCommand(p.command);
+			const r = await execCmd(p.command, opts);
+			_log.push({ shell: opts.shell as string, command: p.command, exitCode: r.exitCode, timedOut: r.timedOut });
+			let o = `Exit code: ${r.exitCode}${EOL}`;
+			if (r.timedOut) o += "Status: TIMED OUT" + EOL;
+			if (r.cancelled) o += "Status: CANCELLED" + EOL;
+			if (r.stdout) o += `${EOL}── stdout ──${EOL}${r.stdout}${EOL}`;
+			if (r.stderr) o += `${EOL}── stderr ──${EOL}${r.stderr}${EOL}`;
+			if (safe.risk === "confirm") o += `${EOL}⚠️  ${safe.reasons.join("; ")}`;
+			return tr(o);
+		} });
+
+	pi.registerTool({ name: "windows_audit_log", label: "Windows: Audit Log", description: "Show command history and exit codes.", promptSnippet: "Show Windows command audit log", promptGuidelines: ["Use to see what was executed."],
+		parameters: Type.Object({ clear: Type.Optional(Type.Boolean({ description: "Clear after viewing." })), ...cs }),
+		execute(_id, p) { const out = _fmt(); if (p.clear) _log.length = 0; return tr(out); } });
+
+	pi.registerTool({ name: "windows_path_to_windows", label: "Windows: Convert to Windows Format", description: "Convert POSIX/WSL path to C:\\...", promptSnippet: "Convert path to Windows", promptGuidelines: ["Use when you have /c/ or /mnt/c/ path."], parameters: Type.Object({ path: Type.String(), ...cs }),
+		execute(_id, p) { return tr(pathUtils.toWindowsPath(p.path)); } });
+	pi.registerTool({ name: "windows_path_to_wsl", label: "Windows: Convert to WSL", description: "Convert Windows path to /mnt/c/...", promptSnippet: "Convert path to WSL", promptGuidelines: ["Use to pass Windows path to WSL."], parameters: Type.Object({ path: Type.String(), ...cs }),
+		execute(_id, p) { return tr(pathUtils.toWslPath(p.path)); } });
+	pi.registerTool({ name: "windows_path_to_gitbash", label: "Windows: Convert to Git Bash", description: "Convert Windows path to /c/...", promptSnippet: "Convert path to Git Bash", promptGuidelines: ["Use to pass Windows path to Git Bash."], parameters: Type.Object({ path: Type.String(), ...cs }),
+		execute(_id, p) { return tr(pathUtils.toGitBashPath(p.path)); } });
+	pi.registerTool({ name: "windows_path_quote", label: "Windows: Quote Path", description: "Quote a path for a Windows shell.", promptSnippet: "Quote path for shell", promptGuidelines: ["Each shell has different quoting rules."], parameters: Type.Object({ path: Type.String(), shell: Type.Optional(sk), ...cs }),
+		execute(_id, p) { return tr(pathUtils.quoteForShell(p.path, rs(p.shell as WindowsShellKind | undefined))); } });
+	pi.registerTool({ name: "windows_safety_classify", label: "Windows: Classify Safety", description: "Check if command is dangerous.", promptSnippet: "Classify command safety", promptGuidelines: ["Returns 'safe' or 'confirm'."], parameters: Type.Object({ command: Type.String(), ...cs }),
+		execute(_id, p) { const r = classifyCommand(p.command); return tr(`Risk: ${r.risk}${r.reasons.length ? "\nReasons:\n  × " + r.reasons.join("\n  × ") : ""}`); } });
+	pi.registerTool({ name: "windows_doctor", label: "Windows: Doctor", description: "Detect installed developer tools.", promptSnippet: "Run Windows doctor", promptGuidelines: ["Checks PATH, WSL, long paths, dev mode."], parameters: Type.Object({ format: Type.Optional(Type.Union([Type.Literal("text"), Type.Literal("json")])), ...cs }),
+		execute(_id, p) { const r = runDoctor(); return tr(p.format === "json" ? JSON.stringify(r, null, 2) : formatDoctorReport(r)); } });
+	pi.registerTool({ name: "windows_tool_discover", label: "Windows: Discover Tool", description: "Check if a tool is in PATH.", promptSnippet: "Check tool availability", promptGuidelines: ["Use to verify a tool is installed."], parameters: Type.Object({ name: Type.String(), ...cs }),
+		execute(_id, p) { try { const r = execFileSync("where", [p.name], { encoding: "utf8", timeout: 3000 }); return tr(`✓ ${p.name} at:\n${r.split(/\r?\n/).filter(Boolean).map(x => `  ${x}`).join(EOL)}`); } catch { return tr(`✗ ${p.name} not in PATH`); } } });
+	pi.registerTool({ name: "windows_wsl_list_distros", label: "Windows: List WSL Distros", description: "List installed WSL distros.", promptSnippet: "List WSL distros", promptGuidelines: ["See what distros are available."], parameters: Type.Object({ ...cs }),
+		execute() { try { const r = execFileSync("wsl.exe", ["-l", "-q"], { encoding: "utf8", timeout: 5000 }); const d = r.split(/\r?\n/).map(s => s.trim()).filter(s => s && !s.toLowerCase().includes("noinstall") && !s.startsWith("Windows")); return tr(d.length ? "Installed WSL distros:\n  × " + d.join("\n  × ") : "No WSL distros found."); } catch { return tr("WSL not available."); } } });
+
+	pi.registerCommand("windows-doctor", { description: "Run Windows Tools Doctor.", handler: async (_a, ctx) => { ctx?.ui?.notify?.("Windows Doctor complete.", "info"); process.stdout.write(formatDoctorReport(runDoctor()) + EOL); } });
+	pi.registerCommand("windows-shell", { description: "Show/set default shell.", handler: async (a, ctx) => {
+		const arg = (a || "").trim().toLowerCase();
+		if (arg) {
+			if (!["pwsh", "powershell", "cmd", "git-bash", "wsl"].includes(arg)) { ctx?.ui?.notify?.("Invalid shell", "warning"); return; }
+			const info = detectShell(arg as WindowsShellKind);
+			if (!info.available) { ctx?.ui?.notify?.(`${info.displayName} unavailable.`, "warning"); return; }
+			process.env.PI_WINDOWS_SHELL = arg;
+			ctx?.ui?.notify?.(`Shell: ${info.displayName}`, "info"); return;
+		}
+		const c = getDefaultShell();
+		process.stdout.write(`Current shell: ${c.displayName} (${c.kind})\nExecutable: ${c.executable}\n`);
+	} });
+
+	pi.on("before_agent_start", async (event) => {
+		if (process.env.PI_WINDOWS_TOOLS_ENABLED === "false" || process.platform !== "win32") return;
+		return { systemPrompt: `${event.systemPrompt}\n\n---\n\n## Windows Environment\n\n${buildShellGuidance(rs())}` };
+	});
+}

package/extensions/lib/audit.ts

@@ -0,0 +1,34 @@
+export interface AuditEntry {
+  timestamp: string;
+  shell: string;
+  command: string;
+  cwd: string;
+  exitCode: number | null;
+  timedOut: boolean;
+  cancelled: boolean;
+}
+
+const log: AuditEntry[] = [];
+const MAX = 500;
+
+export function record(e: AuditEntry): void {
+  log.push(e);
+  if (log.length > MAX) log.shift();
+}
+
+export function entries(): readonly AuditEntry[] { return log; }
+export function clear(): void { log.length = 0; }
+
+function truncate(s: string, n: number): string {
+  return s.length <= n ? s : s.slice(0, n) + "\u2026";
+}
+
+export function format(items?: readonly AuditEntry[]): string {
+  const list = items ?? log;
+  if (list.length === 0) return "No commands executed yet.";
+  return list.map((e, i) => {
+    const flags = [e.timedOut && "TIMED OUT", e.cancelled && "CANCELLED"].filter(Boolean);
+    const tag = flags.length ? " [" + flags.join(", ") + "]" : "";
+    return "[" + (i + 1) + "] " + e.timestamp + "  " + e.shell + "  exit:" + e.exitCode + tag + "\n    cmd: " + truncate(e.command, 300) + "\n    cwd: " + e.cwd;
+  }).join("\n\n");
+}

package/extensions/lib/doctor.ts

@@ -0,0 +1,58 @@
+import { execFileSync } from "node:child_process";
+import * as os from "node:os";
+
+export interface ToolInfo { name: string; found: boolean; path?: string; version?: string; }
+export interface DoctorReport {
+	os: string; osVersion: string; architecture: string; defaultShell: string;
+	tools: ToolInfo[]; wslDistros: string[]; longPathsEnabled: boolean | null; developerMode: boolean | null;
+}
+
+function which(cmd: string): string | null {
+	try { return execFileSync("where", [cmd], { encoding: "utf8", timeout: 3000 }).split(/\r?\n/)[0]?.trim() || null; } catch { return null; }
+}
+function checkTool(name: string, cmd: string, va: string[] = ["--version"]): ToolInfo {
+	const p = which(cmd); let v: string | undefined;
+	if (p) try { v = execFileSync(p, va, { encoding: "utf8", timeout: 3000 }).split(/\r?\n/)[0]?.trim(); } catch {}
+	return { name, found: !!p, path: p || undefined, version: v };
+}
+
+function wslDistros(): string[] {
+	try { return execFileSync("wsl.exe", ["-l", "-q"], { encoding: "utf8", timeout: 5000 }).split(/\r?\n/).map(s => s.trim()).filter(s => s && !s.toLowerCase().includes("noinstall") && !s.startsWith("Windows")); } catch { return []; }
+}
+function regDword(key: string, val: string): boolean | null {
+	try {
+		const out = execFileSync("reg", ["query", key, "/v", val], { encoding: "utf8", timeout: 3000 });
+		const m = out.match(new RegExp(`${val}\\s+REG_DWORD\\s+(0x[0-9a-f]+)`, "i"));
+		return m ? parseInt(m[1], 16) === 1 : null;
+	} catch { return null; }
+}
+
+export function runDoctor(): DoctorReport {
+	const osInfo = { os: os.type(), osVersion: os.release(), architecture: os.arch() };
+	const tools = [
+		checkTool("pwsh", "pwsh"), checkTool("powershell", "powershell"), checkTool("cmd", "cmd"),
+		checkTool("git", "git"), checkTool("bash (Git Bash)", "bash"), checkTool("wsl", "wsl"),
+		checkTool("node", "node"), checkTool("npm", "npm"), checkTool("pnpm", "pnpm"),
+		checkTool("yarn", "yarn"), checkTool("python", "python"), checkTool("py launcher", "py"),
+		checkTool("dotnet", "dotnet"), checkTool("cmake", "cmake"), checkTool("ninja", "ninja"),
+		checkTool("winget", "winget"), checkTool("choco", "choco"), checkTool("scoop", "scoop"),
+		checkTool("ssh", "ssh"), checkTool("msbuild", "msbuild"), checkTool("cl", "cl"),
+		checkTool("devenv", "devenv"), checkTool("reg", "reg"), checkTool("sc", "sc"), checkTool("netsh", "netsh"),
+	];
+	const wslTool = tools.find(t => t.name === "wsl");
+	return {
+		...osInfo, defaultShell: process.env.PI_WINDOWS_SHELL || "pwsh",
+		tools, wslDistros: wslTool?.found ? wslDistros() : [],
+		longPathsEnabled: regDword("HKLM\\SYSTEM\\CurrentControlSet\\Control\\FileSystem", "LongPathsEnabled"),
+		developerMode: regDword("HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\AppModelUnlock", "AllowDevelopmentWithoutDevLicense"),
+	};
+}
+
+export function formatDoctorReport(r: DoctorReport): string {
+	const lines = [`Windows Tools Doctor`, `━━━━━━━━━━━━━━━━━━━`, `OS: ${r.os} ${r.osVersion}`, `Architecture: ${r.architecture}`, `Default shell: ${r.defaultShell}`, "", "── Tools ──"];
+	for (const t of r.tools) lines.push(`  ${t.found ? "✓" : "✗"} ${t.name}${t.version ? ` ${t.version}` : ""}`);
+	if (r.wslDistros.length) { lines.push("", "── WSL Distros ──"); for (const d of r.wslDistros) lines.push(`  • ${d}`); }
+	lines.push("", "── System Features ──", `  Long paths: ${f3(r.longPathsEnabled)}`, `  Developer Mode: ${f3(r.developerMode)}`);
+	return lines.join("\n");
+}
+function f3(v: boolean | null): string { return v === true ? "enabled" : v === false ? "disabled" : "unknown"; }

package/extensions/lib/path-utils.ts

@@ -0,0 +1,104 @@
+import type { WindowsShellKind } from "./shell-detect";
+
+/**
+ * Convert a Windows path (C:\foo\bar) to a Unix-style path (/c/foo/bar).
+ * Handles forward-slash Windows paths, UNC paths, and long-path prefixes.
+ */
+export function toPosixPath(windowsPath: string): string {
+	let p = windowsPath.replace(/\\/g, "/");
+
+	// Strip \\?\ long-path prefix
+	p = p.replace(/^\/\/\?\/+/, "");
+
+	// Handle device paths (\\.\COM1 → \\.\COM1, keep as-is)
+	if (p.match(/^\/{2}\.\//)) return p;
+
+	// Handle UNC paths (\\server\share → //server/share)
+	if (p.startsWith("//") && !p.startsWith("//?/")) {
+		return p.replace(/^\/\/([^/])/, "//$1");
+	}
+
+	// Handle C:/foo → /c/foo or C:foo\bar → /c/foo\bar
+	if (/^[A-Za-z]:/.test(p)) {
+		return p.replace(/^([A-Za-z]):\/?/, (_, d) => `/${d.toLowerCase()}/`);
+	}
+
+	return p;
+}
+
+/**
+ * Convert a POSIX path (/c/foo/bar) to a Windows path (C:\foo\bar).
+ */
+export function toWindowsPath(posixPath: string): string {
+	if (/^[A-Za-z]:[\\/]/.test(posixPath)) {
+		return posixPath.replace(/\//g, "\\");
+	}
+	const wsl = posixPath.match(/^\/mnt\/([a-zA-Z])\/(.+)/);
+	if (wsl) return `${wsl[1].toUpperCase()}:\\${wsl[2].replace(/\//g, "\\")}`;
+	const gb = posixPath.match(/^\/([a-zA-Z])\/(.+)/);
+	if (gb) return `${gb[1].toUpperCase()}:\\${gb[2].replace(/\//g, "\\")}`;
+	return posixPath.replace(/\//g, "\\");
+}
+
+/**
+ * Convert a Windows path to Git Bash format (/c/Users/...).
+ */
+export function toGitBashPath(windowsPath: string): string {
+	return toPosixPath(windowsPath);
+}
+
+/**
+ * Convert a Windows path to WSL format (/mnt/c/Users/...).
+ * Ignores input already in WSL or POSIX format.
+ */
+export function toWslPath(windowsPath: string): string {
+	if (windowsPath.startsWith("/mnt/")) return windowsPath;
+	const posix = toPosixPath(windowsPath);
+	return posix.startsWith("/mnt/") ? posix : `/mnt${posix}`;
+}
+
+/**
+ * Normalize a Windows path: backslashes, uppercase drive, resolve . and ..,
+ * collapse repeated separators.
+ */
+export function normalizeWindowsPath(path: string): string {
+	if (!path) return path;
+	const isUnc = path.startsWith("\\\\") || path.startsWith("//");
+	let n = path.replace(/\//g, "\\").replace(/^([a-z]):\\/, (_, d) => `${d.toUpperCase()}:\\`);
+	if (isUnc) n = "\\" + n.slice(2).replace(/\\\\+/g, "\\");
+	else n = n.replace(/\\\\+/g, "\\");
+	const parts = n.split("\\");
+	const r: string[] = [];
+	for (const p of parts) {
+		if (p === "." || p === "") continue;
+		if (p === "..") { if (r.length > 1) r.pop(); continue; }
+		r.push(p);
+	}
+	return r.join("\\") || (n.endsWith("\\") ? "\\" : "");
+}
+
+/**
+ * Check if a path looks like a Windows absolute path
+ * (C:\..., \\server\..., \\?\..., \\.\...).
+ */
+export function isWindowsAbsolutePath(path: string): boolean {
+	return /^[A-Za-z]:[\\/]|^[\\/]{2}(?:[\\/]?[?.]|[^\\/]+[\\/])/.test(path);
+}
+
+/**
+ * Quote a path for a specific Windows shell.
+ */
+export function quoteForShell(path: string, shell: WindowsShellKind): string {
+	if (!path) return '""';
+	const q = path.includes(" ") || path.includes("\t") || path.includes('"');
+	switch (shell) {
+		case "pwsh":
+		case "powershell":
+			return q ? `'${path.replace(/'/g, "''")}'` : path;
+		case "cmd":
+			return q ? `"${path.replace(/"/g, '""')}"` : path;
+		case "git-bash":
+		case "wsl":
+			return q ? `'${path.replace(/'/g, "'\\''")}'` : path;
+	}
+}

package/extensions/lib/prompts.ts

@@ -0,0 +1,115 @@
+import type { WindowsShellKind } from "./shell-detect";
+
+export interface ShellPrompt {
+	kind: WindowsShellKind;
+	guidance: string;
+	syntaxNote: string;
+	forbiddenPatterns: string[];
+	preferredCommands: string[];
+}
+
+const pwshPrompt: ShellPrompt = {
+	kind: "pwsh",
+	guidance: "You are running on Windows using PowerShell 7+.",
+	syntaxNote: `
+Use PowerShell syntax:
+- Environment variables: $env:NAME = "value"
+- Filesystem: Get-ChildItem, Get-Content, Set-Content, Copy-Item, Move-Item, Remove-Item, New-Item
+- Text search: Select-String -Path <file> -Pattern <regex>
+- Command separator: ;
+- Native exit codes: $LASTEXITCODE
+- Quote paths with spaces
+- Prefer Node.js internal file tools for editing files
+`,
+	forbiddenPatterns: [
+		"rm -rf (use Remove-Item -Recurse -Force)",
+		"cp (use Copy-Item)",
+		"mv (use Move-Item)",
+		"grep (use Select-String)",
+		"export VAR=value (use $env:VAR = 'value')",
+		"sed/awk (use PowerShell string operations or -replace)",
+	],
+	preferredCommands: ["Get-ChildItem", "Get-Content", "Set-Content", "Copy-Item", "Move-Item", "Remove-Item", "New-Item", "Select-String"],
+};
+
+const cmdPrompt: ShellPrompt = {
+	kind: "cmd",
+	guidance: "You are running on Windows using cmd.exe.",
+	syntaxNote: `
+Use cmd.exe syntax:
+- Environment variables: set NAME=value
+- Filesystem: dir, type, copy, move, del, rmdir
+- Prefer PowerShell if available for complex operations
+- Command separator: &&
+- Paths with spaces should be double-quoted
+`,
+	forbiddenPatterns: [
+		"rm (use del or rmdir)",
+		"ls (use dir)",
+		"export (use set)",
+	],
+	preferredCommands: ["dir", "type", "copy", "move", "del", "rmdir", "mkdir"],
+};
+
+const gitBashPrompt: ShellPrompt = {
+	kind: "git-bash",
+	guidance: "You are running on Windows using Git Bash.",
+	syntaxNote: `
+Use POSIX-style commands (bash syntax):
+- Environment: export NAME=value
+- Commands: ls, cp, mv, rm, grep, sed, awk
+- Windows paths need conversion: C:\\Users\\... → /c/Users/...
+- Be careful when passing paths to Windows-native tools
+`,
+	forbiddenPatterns: [],
+	preferredCommands: ["ls", "cp", "mv", "rm", "grep", "find", "cat", "echo"],
+};
+
+const wslPrompt: ShellPrompt = {
+	kind: "wsl",
+	guidance: "You are running through WSL2 (Windows Subsystem for Linux).",
+	syntaxNote: `
+Use Linux shell syntax (bash):
+- Environment: export NAME=value
+- Commands: ls, cp, mv, rm, grep, sed, awk
+- Workspace paths should use /mnt/c/... convention
+- Do NOT call Windows-only tools unless explicitly routed through powershell.exe or cmd.exe
+- Use WSL for Linux-native projects: OpenWrt, Yocto, kernel builds
+`,
+	forbiddenPatterns: [
+		"C:\\ paths (convert to /mnt/c/...)",
+	],
+	preferredCommands: ["ls", "cp", "mv", "rm", "grep", "find", "cat", "echo", "make", "gcc"],
+};
+
+export function getPromptForShell(kind: WindowsShellKind): ShellPrompt {
+	switch (kind) {
+		case "pwsh": return pwshPrompt;
+		case "powershell": return pwshPrompt; // same guidance
+		case "cmd": return cmdPrompt;
+		case "git-bash": return gitBashPrompt;
+		case "wsl": return wslPrompt;
+	}
+}
+
+export function buildShellGuidance(kind: WindowsShellKind): string {
+	const prompt = getPromptForShell(kind);
+	const lines = [
+		prompt.guidance,
+		prompt.syntaxNote.trim(),
+	];
+
+	if (prompt.forbiddenPatterns.length > 0) {
+		lines.push("", "Avoid these commands (they don't work in this shell):");
+		for (const p of prompt.forbiddenPatterns) {
+			lines.push(`  • ${p}`);
+		}
+	}
+
+	lines.push("", "Preferred commands:");
+	for (const cmd of prompt.preferredCommands) {
+		lines.push(`  • ${cmd}`);
+	}
+
+	return lines.join("\n");
+}