@gogomi/pi-windows-shell 0.1.0

package/output.ts

@@ -0,0 +1,139 @@
+/**
+ * Output truncation and tail reading utilities
+ */
+
+import fs from "node:fs";
+import { createReadStream } from "node:fs";
+import type { TailResult } from "./types.js";
+
+const DEFAULT_MAX_BYTES = 50000;
+const DEFAULT_TAIL_LINES = 100;
+
+/**
+ * Read lines from the end of a file (tail functionality).
+ */
+export async function tailFile(
+  filePath: string,
+  options: {
+    lines?: number;
+    maxBytes?: number;
+  } = {}
+): Promise<TailResult> {
+  const lines = options.lines ?? DEFAULT_TAIL_LINES;
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+
+  try {
+    await fs.promises.access(filePath);
+  } catch {
+    return {
+      lines: [],
+      truncated: false,
+      totalLines: 0,
+      linesRead: 0,
+      fileExists: false,
+    };
+  }
+
+  try {
+    const stats = await fs.promises.stat(filePath);
+    const fileSize = stats.size;
+
+    // If file is small enough, read it all
+    if (fileSize <= maxBytes) {
+      const content = await fs.promises.readFile(filePath, "utf-8");
+      const allLines = content.split(/\r?\n/).filter((l) => l.length > 0);
+      const tailLines = allLines.slice(-lines);
+      
+      return {
+        lines: tailLines,
+        truncated: allLines.length > tailLines.length,
+        totalLines: allLines.length,
+        linesRead: tailLines.length,
+        fileExists: true,
+      };
+    }
+
+    // For large files, stream from the end
+    const buffer = Buffer.alloc(maxBytes);
+    const fd = await fs.promises.open(filePath, "r");
+    
+    try {
+      // Read from near the end
+      const startPos = Math.max(0, fileSize - maxBytes);
+      const { bytesRead } = await fd.read(buffer, 0, maxBytes, startPos);
+      const content = buffer.toString("utf-8", 0, bytesRead);
+      
+      // Split and find tail lines
+      const allLines = content.split(/\r?\n/);
+      
+      // Skip partial first line if we started mid-line
+      const skipPartial = startPos > 0 && !content.startsWith("\n") && !content.startsWith("\r");
+      const lineStart = skipPartial ? 1 : 0;
+      
+      const totalLines = allLines.length - lineStart;
+      const tailStartIndex = Math.max(lineStart, allLines.length - lines);
+      const tailLines = allLines.slice(tailStartIndex);
+      
+      return {
+        lines: tailLines,
+        truncated: tailStartIndex > lineStart,
+        totalLines,
+        linesRead: tailLines.length,
+        fileExists: true,
+      };
+    } finally {
+      await fd.close();
+    }
+  } catch (error) {
+    throw new Error(
+      `Failed to read output file: ${filePath}. Error: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Truncate output text to a maximum size.
+ */
+export function truncateOutput(
+  text: string,
+  options: {
+    maxBytes?: number;
+    maxLines?: number;
+  } = {}
+): { text: string; truncated: boolean } {
+  const maxBytes = options.maxBytes ?? 50000;
+  const maxLines = options.maxLines ?? 2000;
+
+  // Check line limit
+  const lines = text.split(/\r?\n/);
+  if (lines.length > maxLines) {
+    const truncatedLines = lines.slice(0, maxLines);
+    return {
+      text: truncatedLines.join("\n") + `\n[output truncated: showing first ${maxLines} lines of ${lines.length}]`,
+      truncated: true,
+    };
+  }
+
+  // Check byte limit
+  if (Buffer.byteLength(text, "utf-8") > maxBytes) {
+    let truncatedText = "";
+    let currentBytes = 0;
+    
+    for (const line of lines) {
+      const lineBytes = Buffer.byteLength(line + "\n", "utf-8");
+      if (currentBytes + lineBytes > maxBytes) {
+        break;
+      }
+      truncatedText += line + "\n";
+      currentBytes += lineBytes;
+    }
+    
+    return {
+      text: truncatedText.trimEnd() + `\n[output truncated: ${Buffer.byteLength(text, "utf-8")} bytes down to ${maxBytes} bytes]`,
+      truncated: true,
+    };
+  }
+
+  return { text, truncated: false };
+}
+

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@gogomi/pi-windows-shell",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Windows PowerShell and process-management tools for Pi coding agent.",
+  "main": "index.ts",
+  "files": [
+    "index.ts",
+    "shell.ts",
+    "output.ts",
+    "paths.ts",
+    "process-registry.ts",
+    "types.ts",
+    "prompts/windows-shell-policy.md",
+    "tsconfig.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "powershell",
+    "windows",
+    "process-management"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gogomy/pi-windows-shell.git"
+  },
+  "license": "MIT",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "prompts": [
+      "./prompts"
+    ]
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/paths.ts

@@ -0,0 +1,66 @@
+/**
+ * Path helpers for pi-windows-shell
+ */
+
+import path from "node:path";
+import os from "node:os";
+
+/**
+ * Get the base directory for pi-windows-shell data.
+ * Uses LOCALAPPDATA, falls back to TEMP.
+ */
+export function getBaseDir(): string {
+  const localAppData = process.env.LOCALAPPDATA;
+  if (localAppData) {
+    return path.join(localAppData, "pi-windows-shell");
+  }
+  return path.join(os.tmpdir(), "pi-windows-shell");
+}
+
+/**
+ * Get the registry file path.
+ */
+export function getRegistryPath(): string {
+  return path.join(getBaseDir(), "processes.json");
+}
+
+/**
+ * Get the logs directory path.
+ */
+export function getLogsDir(): string {
+  return path.join(getBaseDir(), "logs");
+}
+
+/**
+ * Generate a default output file path for a new process.
+ */
+export function getDefaultOutputFile(name: string): string {
+  const timestamp = Date.now().toString(36);
+  const safeName = (name || "process")
+    .replace(/[^a-zA-Z0-9_-]/g, "_")
+    .replace(/_{2,}/g, "_")
+    .slice(0, 50);
+  
+  const logsDir = getLogsDir();
+  return path.join(logsDir, `${timestamp}-${safeName}.log`);
+}
+
+/**
+ * Ensure a directory exists, creating it if necessary.
+ */
+export async function ensureDir(dirPath: string): Promise<void> {
+  const { mkdir } = await import("node:fs/promises");
+  await mkdir(dirPath, { recursive: true });
+}
+
+/**
+ * Generate a unique process ID.
+ */
+export function generateProcessId(name: string): string {
+  const timestamp = Date.now().toString(36);
+  const safeName = (name || "process")
+    .replace(/[^a-zA-Z0-9_-]/g, "_")
+    .slice(0, 20);
+  return `${timestamp}-${safeName}`;
+}
+

package/process-registry.ts

@@ -0,0 +1,210 @@
+/**
+ * Persistent process registry for pi-windows-shell
+ */
+
+import fs from "node:fs";
+import type { ProcessRegistry, ManagedProcess } from "./types.js";
+import { getRegistryPath, ensureDir, getBaseDir } from "./paths.js";
+
+const REGISTRY_VERSION = "1.0.0";
+
+/**
+ * Ensure the base directory exists.
+ */
+async function ensureBaseDir(): Promise<void> {
+  await ensureDir(getBaseDir());
+}
+
+/**
+ * Load the process registry from disk.
+ */
+export async function loadRegistry(): Promise<ProcessRegistry> {
+  try {
+    await ensureBaseDir();
+    const path = getRegistryPath();
+    
+    try {
+      await fs.promises.access(path);
+    } catch {
+      // File doesn't exist, return empty registry
+      return { version: REGISTRY_VERSION, processes: [] };
+    }
+
+    const content = await fs.promises.readFile(path, "utf-8");
+    const data = JSON.parse(content) as ProcessRegistry;
+    
+    // Validate version
+    if (!data.version || !Array.isArray(data.processes)) {
+      return { version: REGISTRY_VERSION, processes: [] };
+    }
+
+    return data;
+  } catch (error) {
+    console.error(`Failed to load registry: ${error}`);
+    return { version: REGISTRY_VERSION, processes: [] };
+  }
+}
+
+/**
+ * Save the process registry to disk.
+ */
+export async function saveRegistry(registry: ProcessRegistry): Promise<void> {
+  try {
+    await ensureBaseDir();
+    const path = getRegistryPath();
+    await fs.promises.writeFile(path, JSON.stringify(registry, null, 2), "utf-8");
+  } catch (error) {
+    throw new Error(
+      `Failed to save registry: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Add a new process to the registry.
+ */
+export async function addProcess(process: ManagedProcess): Promise<void> {
+  const registry = await loadRegistry();
+  registry.processes.push(process);
+  await saveRegistry(registry);
+}
+
+/**
+ * Update a process in the registry.
+ */
+export async function updateProcess(id: string, updates: Partial<ManagedProcess>): Promise<boolean> {
+  const registry = await loadRegistry();
+  const index = registry.processes.findIndex((p) => p.id === id);
+  
+  if (index === -1) {
+    return false;
+  }
+
+  registry.processes[index] = { ...registry.processes[index], ...updates };
+  await saveRegistry(registry);
+  return true;
+}
+
+/**
+ * Remove a process from the registry.
+ */
+export async function removeProcess(id: string): Promise<boolean> {
+  const registry = await loadRegistry();
+  const initialLength = registry.processes.length;
+  registry.processes = registry.processes.filter((p) => p.id !== id);
+  
+  if (registry.processes.length === initialLength) {
+    return false;
+  }
+
+  await saveRegistry(registry);
+  return true;
+}
+
+/**
+ * Get a process by ID.
+ */
+export async function getProcess(id: string): Promise<ManagedProcess | null> {
+  const registry = await loadRegistry();
+  return registry.processes.find((p) => p.id === id) ?? null;
+}
+
+/**
+ * Get all processes.
+ */
+export async function getAllProcesses(): Promise<ManagedProcess[]> {
+  const registry = await loadRegistry();
+  return registry.processes;
+}
+
+/**
+ * Remove multiple processes by IDs.
+ */
+export async function removeProcesses(ids: string[]): Promise<number> {
+  const registry = await loadRegistry();
+  const initialLength = registry.processes.length;
+  const idSet = new Set(ids);
+  registry.processes = registry.processes.filter((p) => !idSet.has(p.id));
+  
+  const removed = initialLength - registry.processes.length;
+  if (removed > 0) {
+    await saveRegistry(registry);
+  }
+  return removed;
+}
+
+/**
+ * Clean up stale registry entries.
+ */
+export async function cleanupRegistry(options: {
+  removeExited?: boolean;
+  deleteLogs?: boolean;
+  olderThanDays?: number;
+}): Promise<{
+  removedEntries: number;
+  deletedLogs: number;
+  keptRunning: number;
+}> {
+  const registry = await loadRegistry();
+  const toRemove: string[] = [];
+  let deletedLogs = 0;
+
+  // Handle log deletion
+  if (options.deleteLogs && options.olderThanDays) {
+    const olderThan = Date.now() - options.olderThanDays * 24 * 60 * 60 * 1000;
+    
+    for (const proc of registry.processes) {
+      try {
+        const stat = await fs.promises.stat(proc.outputFile);
+        if (stat.mtimeMs < olderThan) {
+          await fs.promises.unlink(proc.outputFile);
+          deletedLogs++;
+        }
+      } catch {
+        // File doesn't exist or can't be accessed, skip
+      }
+    }
+  }
+
+  // Handle registry entry removal
+  if (options.removeExited) {
+    for (const proc of registry.processes) {
+      if (proc.status === "exited") {
+        toRemove.push(proc.id);
+      }
+    }
+  }
+
+  const removedEntries = toRemove.length;
+  if (removedEntries > 0) {
+    await removeProcesses(toRemove);
+  }
+
+  // Count kept running processes, excluding those just removed
+  const removedIds = new Set(toRemove);
+  const remaining = registry.processes.filter(
+    (p) => !removedIds.has(p.id) && p.status === "running"
+  );
+  
+  return {
+    removedEntries,
+    deletedLogs,
+    keptRunning: remaining.length,
+  };
+}
+
+/**
+ * Check if a process with given PID is still alive.
+ * Returns the process status or null if not found.
+ */
+export async function checkProcessAlive(pid: number): Promise<"running" | "exited" | "unknown"> {
+  try {
+    // Try using Node's process kill check
+    process.kill(pid, 0);
+    return "running";
+  } catch {
+    // ESRCH means process doesn't exist
+    // Other errors may mean permission issues
+    return "exited";
+  }
+}

package/prompts/windows-shell-policy.md

@@ -0,0 +1,113 @@
+# Windows Shell Policy
+
+The environment runs on Windows.
+
+These rules are always active when choosing how to run commands.
+
+## Shell/tool selection
+
+Use Bash only for Git-oriented and Unix-like repository inspection workflows:
+
+- `git status`
+- `git diff`
+- `git log`
+- `git grep`
+- patch inspection
+- Unix-style text pipelines
+- `grep`, `sed`, `awk`, `find`, `xargs`
+
+Use PowerShell for Windows-native workflows:
+
+- Windows paths such as `C:\...` or `D:\...`
+- Windows environment variables such as `$env:USERPROFILE`
+- `.exe`, `.cmd`, `.bat`, `.ps1`
+- process management
+- killing processes by PID or port
+- checking installed commands with `Get-Command`
+- Python virtual environments on Windows
+- npm/yarn/pnpm/npx commands that resolve through `.cmd` launchers
+- Windows services, registry, or system configuration
+- launching Windows executables such as Godot, Blender, editors, or installers
+
+Do not mix Bash syntax and PowerShell syntax in the same command.
+
+Prefer `git diff` over shell-specific `diff` when inspecting repository changes.
+
+## Windows path handling
+
+Do not assume Windows paths are valid inside Bash.
+
+If a command uses a Windows path such as:
+
+```txt
+C:\...
+D:\...
+```
+
+use PowerShell.
+
+Do not manually convert Windows paths to `/mnt/c/...`, `/c/...`, or `/d/...` unless the active Bash environment has already been verified to support that path style.
+
+Do not assume WSL is available.
+
+## Long-running commands
+
+Do not use Bash background syntax on Windows:
+
+```bash
+npm run dev &
+```
+
+For long-running commands, background servers, file watchers, REPLs, or GUI applications, use the environment-provided Windows process tools when available:
+
+- `win_start_process`
+- `win_process_status`
+- `win_read_output`
+- `win_stop_process`
+- `win_list_processes`
+
+For stuck ports, use the environment-provided port tool when available:
+
+- `win_kill_port`
+
+Examples of long-running or blocking commands include:
+
+- `npm run dev`
+- `pnpm dev`
+- `yarn dev`
+- `godot . -e`
+- local web servers
+- file watchers
+- REPLs
+- GUI applications
+
+## Command availability
+
+Do not assume project-specific executable paths or tool names globally.
+
+If a command is unavailable, diagnose it before retrying.
+
+For PowerShell-native checks, use:
+
+```powershell
+Get-Command <command-name> -ErrorAction SilentlyContinue
+```
+
+If the environment provides `win_which`, it may also be used for Windows command resolution.
+
+For Bash-only tools, use Bash diagnostics only after confirming the command is intended to run in Bash.
+
+## Failure handling
+
+When a command fails, do not retry blindly.
+
+Identify:
+
+1. Which shell/tool ran it.
+2. The current working directory.
+3. The exit code.
+4. stderr/stdout.
+5. Whether the command is Windows-native, Unix-like, or environment-provided.
+6. Whether the path syntax matches the selected shell.
+
+Then choose the corrected shell or tool before retrying.