@aliou/pi-processes 0.6.3 → 0.7.0

package/CONTRIBUTING.md

@@ -0,0 +1,123 @@
+# Contributing
+
+## Scope
+
+`README.md` is for users.
+
+Keep development details, testing notes, internal tool guidance, and docs build details in this file.
+
+## Development
+
+Install dependencies:
+
+```bash
+pnpm install
+```
+
+Run checks:
+
+```bash
+pnpm lint
+pnpm typecheck
+```
+
+## Repository layout
+
+- `src/` - extension source
+- `src/tools/` - `process` tool and actions
+- `src/commands/` - `/ps` commands and settings UI
+- `src/hooks/` - lifecycle hooks, blocker, message rendering, widgets
+- `src/components/` - TUI components
+- `skills/` - shipped package skills
+- `.agents/skills/` - local repo-only skills for development workflows
+- `.github/docs-site/` - isolated docs page build
+
+## Internal behavior
+
+This extension is mainly for agent-managed background processes.
+
+Typical flow:
+
+1. Pi starts a long-running command in the background.
+2. Pi continues other work.
+3. The user watches, pins, or kills the process from the UI.
+4. Pi inspects output or logs when needed.
+
+Use the `process` tool for long-running commands such as dev servers, test watchers, build watchers, and log tails.
+
+Avoid shell background patterns when the process tool fits.
+
+Background command blocking is optional. It is controlled by `interception.blockBackgroundCommands`.
+
+## Testing
+
+Useful local checks:
+
+```bash
+pnpm lint
+pnpm typecheck
+```
+
+Useful manual process scripts:
+
+```bash
+./test/test-output.sh
+./test/test-exit-success.sh 5
+./test/test-exit-failure.sh 5
+./test/test-exit-crash.sh 5
+```
+
+## Docs conventions
+
+### README
+
+Keep `README.md` focused on user outcomes:
+
+- what the extension does
+- how users interact with it
+- slash commands and UI behavior
+- troubleshooting
+
+Avoid putting these in `README.md`:
+
+- dev commands
+- test commands
+- internal architecture details
+- detailed tool-call schemas
+- release workflow notes
+
+### Video placeholders
+
+Use HTML comments in `README.md`:
+
+```md
+<!-- VIDEO: {"id":"process-panel","title":"Browse and manage processes from the panel"} -->
+```
+
+GitHub ignores these comments. The docs page build turns them into video blocks.
+
+Add one placeholder for each feature section.
+
+## Docs page build
+
+The generated docs page lives under `.github/docs-site/` and is isolated from the extension source.
+
+It reads `README.md`, converts markdown into structured content, replaces video placeholders, highlights code with Shiki, and builds a static page with Vite and Tailwind.
+
+The GitHub Actions workflow for this lives in `.github/workflows/docs-page.yml`.
+
+## Demo pattern
+
+For demo recording, use a small self-contained project with a realistic workflow.
+
+The best pattern used for this extension was a fake Northwind API project where Pi:
+
+1. starts a server in the background
+2. runs tests and sees failures
+3. runs migrations
+4. checks server logs
+5. updates seed data
+6. reruns tests
+7. cleans up the process
+
+That pattern shows why background processes matter in a normal task instead of showing features one by one.

package/README.md

@@ -1,155 +1,186 @@
-# Processes Extension
+# pi-processes
 
-Manage background processes from Pi. Start long-running commands (dev servers, build watchers, log tailers) without blocking the conversation.
+Manage background processes from Pi without blocking the conversation.
 
-## Demo
+This extension lets Pi keep long-running commands alive while the conversation continues. It is useful for dev servers, test watchers, local APIs, builds, and log tails.
 
-<video src="https://assets.aliou.me/pi-extensions/2026-01-26-processes-demo.mp4" controls playsinline muted></video>
+## Let Pi keep working while processes run
+
+When a task needs a long-running command, Pi can start it in the background by itself and keep helping with the rest of the work.
+
+That means Pi can, for example:
+
+- start a dev server and keep coding
+- keep a test watcher running while it fixes failures
+- run a local API while it inspects logs
+- watch build output without blocking the conversation
+
+You can then inspect, pin, or stop those processes from the UI.
+
+<!-- VIDEO: {"id":"agent-starts-processes","title":"Pi starts a long-running process and keeps working"} -->
 
 ## Installation
 
+From npm:
+
 ```bash
 pi install npm:@aliou/pi-processes
 ```
 
-Or from git:
+From git:
 
 ```bash
 pi install git:github.com/aliou/pi-processes
 ```
 
-## Features
+## Open the process panel
 
-- **Tool**: `process` with actions: `start`, `list`, `output`, `logs`, `kill`, `clear`
-- **Commands**: `/ps` (interactive panel), `/ps:pin` (pin dock to process), `/ps:logs` (open log overlay), `/ps:kill` (kill process), `/ps:clear` (clear finished), `/ps:dock` (control dock visibility), `/ps:settings`
-- **Log Dock**: Unified view for all process logs with color-coded prefixes
-- **Follow Mode**: Automatically shows dock when processes start (enabled by default)
-- **Focus Mode**: Filter to a single process's logs
-- Auto-cleanup on session exit
-- File-based logging (logs written to temp files, not memory)
-- Friendly process names (auto-inferred or custom)
+Use `/ps` to open the main process panel.
 
-## Usage
+From there you can:
 
-### Tool (for agent)
+- see running and finished processes
+- inspect recent output
+- pin a process to the dock
+- kill a running process
+- clear finished entries
 
-```
-process start "pnpm dev" name="backend-dev"
-process start "pnpm build" name="build" alertOnSuccess=true
-process start "pnpm test" alertOnFailure=true
-process list
-process output id="backend"
-process logs id="proc_1"
-process kill id="backend"
-process clear
-```
+Keys:
+
+- `j/k` or arrow keys: move selection
+- `J/K`: scroll preview
+- `enter`: pin selected process to the dock
+- `x`: kill selected process
+- `c`: clear finished processes
+- `q` or `esc`: close
+
+<!-- VIDEO: {"id":"process-panel","title":"Browse and manage processes from the panel"} -->
+
+## Inspect logs
 
-**Alert parameters** (for `start` action):
-- `alertOnSuccess` (default: false) - Get a turn to react when process completes successfully. Use for builds/tests where you need confirmation.
-- `alertOnFailure` (default: true) - Get a turn to react when process fails/crashes. Use to be alerted of unexpected failures.
-- `alertOnKill` (default: false) - Get a turn to react if killed by external signal. Note: killing via tool never triggers a turn.
+Use `/ps:logs [id|name]` to open the log overlay for one process.
 
-**Important:** You don't need to poll or wait for processes. Notifications arrive automatically based on your preferences. Start processes and continue with other work - you'll be informed if something requires attention.
+This is useful when Pi started a server, watcher, or local API and you want to follow what it is doing in more detail.
 
-Note: User always sees process updates in the UI. The alert flags control whether the agent gets a turn to react (e.g. check results, fix code, restart).
+Keys:
 
-### Commands (interactive)
+- `tab` / `shift+tab`: switch process tabs
+- `g/G`: jump to top or bottom
+- `j/k` or arrow keys: scroll
+- `s`: switch between combined, stdout, and stderr
+- `f`: toggle follow mode
+- `/`: search
+- `n/N`: move between search matches
+- `q` or `esc`: close
 
-#### `/ps` - Open full panel
+<!-- VIDEO: {"id":"inspect-logs","title":"Open the log overlay and inspect output"} -->
 
-View and manage all processes in an interactive panel:
-- `j/k` - select process
-- `J/K` - scroll logs
-- `enter` - focus on selected process
-- `x` - kill selected process
-- `c` - clear finished processes
-- `q` - quit
+## Pin one process
 
-#### `/ps:pin [id|name]` - Pin dock to a process
+Use `/ps:pin [id|name]` to keep the dock focused on one process.
 
-Pin the dock to a specific process. Opens the dock automatically if hidden.
+This is useful when one process matters more than the others, such as a dev server or a test watcher.
 
-Without arguments, shows a picker to select a process.
+Without arguments, Pi shows a picker.
 
-#### `/ps:logs [id|name]` - Open log overlay
+<!-- VIDEO: {"id":"pin-process","title":"Pin the dock to one process"} -->
 
-Open the interactive log viewer overlay (search, scroll, stream filter).
+## Control the dock
 
-#### `/ps:kill [id|name]` - Kill a process
+Use `/ps:dock [show|hide|toggle]` to control dock visibility.
 
-Kill a running process. Without arguments, shows a picker.
+The dock gives you a compact live view without leaving the conversation.
 
-#### `/ps:clear` - Clear finished
+<!-- VIDEO: {"id":"dock-control","title":"Show, hide, and use the dock"} -->
 
-Remove all finished processes from the list.
+## Adjust settings
 
-#### `/ps:dock [show|hide|toggle]` - Control dock
+Use `/ps:settings` to configure the extension.
 
-Control dock visibility. Without arguments, it toggles state. With arguments:
-- `show` - Show dock (open)
-- `hide` - Hide dock
-- `toggle` - Cycle dock visibility state
+Available settings include:
 
-### Log Dock
+- process list size
+- output limits
+- shell path override
+- dock defaults
+- follow mode behavior
+- optional background command interception
 
-The log dock shows interleaved logs from all processes with color-coded prefixes:
+<!-- VIDEO: {"id":"settings","title":"Adjust process extension settings"} -->
 
+## Platform support
+
+- macOS: supported
+- Linux: supported
+- Windows: not supported
+
+## Runtime log watch alerts
+
+Use `process` tool `start` with `logWatches` to trigger immediate alerts while the process is still running.
+
+- default behavior: each watch fires once (`repeat: false`)
+- set `repeat: true` to trigger on every match
+- scope by stream (`stdout`, `stderr`, `both`) to reduce noise
+
+Example: server ready marker (one-time default)
+
+```json
+{
+  "action": "start",
+  "name": "dev-server",
+  "command": "pnpm dev",
+  "logWatches": [
+    { "pattern": "ready on http://localhost:3000" }
+  ]
+}
 ```
-[dev]   GET /api/users 200 45ms    (cyan)
-[test]  Running auth.test.ts...    (yellow)
-[dev]   POST /api/auth 200 12ms
-[test]  ✓ login flow
-...
+
+Example: error marker from stderr
+
+```json
+{
+  "action": "start",
+  "name": "builder",
+  "command": "pnpm build --watch",
+  "logWatches": [
+    { "pattern": "TypeError|ReferenceError", "stream": "stderr" }
+  ]
+}
 ```
 
-**Dock Keyboard Shortcuts** (when dock is open):
-- `h` - focus previous process
-- `l` - focus next process
-- `f` - toggle focus mode (filter to single process)
-- `x` - kill focused process
-- `q` - close/unfocus dock
-- Follow mode toggle is only available via settings (`/ps:settings`)
+Example: repeatable watch on stdout only
+
+```json
+{
+  "action": "start",
+  "name": "worker",
+  "command": "pnpm worker",
+  "logWatches": [
+    { "pattern": "job completed", "stream": "stdout", "repeat": true }
+  ]
+}
+```
 
-**Dock States:**
-- `collapsed` (1-2 lines): Summary + last log line
-- `open` (8-12 lines): Full interleaved or focused logs
+Invalid regex patterns fail fast at process start with a clear error.
 
-### Deprecated Commands (backward compatible)
+## Troubleshooting
 
-The following commands are deprecated but still work with a warning:
-- `/process:list` → Use `/ps` instead
-- `/process:stream` → Use `/ps:pin` instead
-- `/process:logs` → Use `/ps:logs` instead
-- `/process:kill` → Use `/ps:kill` instead
-- `/process:clear` → Use `/ps:clear` instead
+### Pi started something and I want to see more output
 
-## Settings
+Open `/ps` for a quick overview, or use `/ps:logs` for full logs.
 
-Configure via `/ps:settings` or `~/.pi/agent/extensions/processes.json`:
+### I want one process to stay visible
 
-- **Widget**: Dock default state, dock height
-- **Follow Mode**: Enable by default, auto-hide on finish
-- **Process List**: Max visible processes, max preview lines
-- **Output Limits**: Default tail lines, max output lines
-- **Execution**: Shell path override
-- **Interception**: Block background commands
+Use `/ps:pin` to focus the dock on that process.
 
-## Test Scripts
+### I want Pi to avoid shell background tricks
 
-Test scripts in `src/test/` directory:
+Enable background command interception in `/ps:settings`. When enabled, Pi avoids normal shell background patterns and uses the process workflow instead.
 
-```bash
-./src/test/test-output.sh          # Continuous output (80 chars/sec)
-./src/test/test-exit-success.sh 5  # Exits successfully after 5s
-./src/test/test-exit-failure.sh 5  # Exits with code 1 after 5s
-./src/test/test-exit-crash.sh 5    # Exits with code 137 after 5s
-```
+## Contributing
+
+For development, testing, docs generation, and extension internals, see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-## Future Improvements
+## License
 
-- [ ] **Configurable keybindings UI**: Allow editing keybindings in settings panel
-- [ ] **Process filtering**: Filter by name/status in full panel
-- [ ] **Log search**: Search within logs (Ctrl+F in dock)
-- [ ] **Copy log path**: Keyboard shortcut to copy log file path
-- [ ] **Open in editor**: Keyboard shortcut to open logs in $EDITOR
-- [ ] **Sound notifications**: Play sound on process completion
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-processes",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -18,6 +18,9 @@
     "extensions": [
       "./src/index.ts"
     ],
+    "skills": [
+      "./skills/pi-processes"
+    ],
     "video": "https://assets.aliou.me/pi-extensions/demos/pi-processes.mp4"
   },
   "publishConfig": {
@@ -25,7 +28,9 @@
   },
   "files": [
     "src",
-    "README.md"
+    "skills",
+    "README.md",
+    "CONTRIBUTING.md"
   ],
   "dependencies": {
     "@aliou/pi-utils-settings": "^0.10.0",
@@ -64,6 +69,7 @@
     "check:lockfile": "pnpm install --frozen-lockfile --ignore-scripts",
     "changeset": "changeset",
     "version": "changeset version",
+    "test": "vitest run",
     "release": "pnpm changeset publish"
   }
 }

package/skills/pi-processes/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: pi-processes
+description: Manage long-running commands in the background with the process tool. Use when a task needs a dev server, test watcher, build watcher, local API, or log tail to keep running while the conversation continues.
+---
+
+# pi-processes
+
+Use this skill when work needs a long-running command to stay alive while Pi continues with other steps.
+
+## Prefer this workflow
+
+- Use the `process` tool for long-running commands.
+- Avoid shell background patterns when the process tool fits.
+- Give processes stable, clear names.
+- Continue the task after starting a process instead of waiting on it.
+- Inspect output or log files only when needed.
+- Kill and clear processes when they are no longer useful.
+
+## Good fits
+
+- `pnpm dev`
+- `npm run server`
+- `pnpm test --watch`
+- `tail -f <logfile>`
+- local preview or build watchers
+
+## Typical flow
+
+1. Start the long-running command with a clear name.
+2. Continue the main task.
+3. Inspect `output` or `logs` if something needs attention.
+4. Use alert flags when success or failure should trigger a follow-up turn.
+5. Kill and clear the process when done.
+
+## Notes
+
+- Users can inspect and manage running processes from `/ps`.
+- Use `write` when a process expects stdin input.
+- Use `output` for a quick tail and `logs` when the full log files are more useful.

package/src/commands/kill/command.ts

@@ -19,7 +19,7 @@ export function registerPsKillCommand(
       let processId: string | undefined;
 
       if (arg) {
-        const proc = manager.find(arg);
+        const proc = manager.get(arg);
         if (!proc) {
           return;
         }
@@ -49,18 +49,18 @@ export function registerPsKillCommand(
         }
       }
 
+      if (!processId) return;
+
       const proc = manager.get(processId);
-      if (!proc) {
-        return;
-      }
+      if (!proc) return;
 
       const signal =
         proc.status === "terminate_timeout" ? "SIGKILL" : "SIGTERM";
       const timeoutMs = signal === "SIGKILL" ? 200 : 3000;
-      const result = await manager.kill(processId, { signal, timeoutMs });
+      const result = await manager.kill(proc.id, { signal, timeoutMs });
 
       if (result.ok) {
-        if (dockActions.getFocusedProcessId() === processId) {
+        if (dockActions.getFocusedProcessId() === proc.id) {
           dockActions.setFocus(null);
         }
       }

package/src/commands/logs/command.ts

@@ -18,7 +18,7 @@ export function registerPsLogsCommand(
       let processId: string | undefined;
 
       if (arg) {
-        const proc = manager.find(arg);
+        const proc = manager.get(arg);
         if (!proc) return;
         processId = proc.id;
       }

package/src/commands/pin/command.ts

@@ -17,7 +17,7 @@ export function registerPsPinCommand(
       let processId: string | undefined;
 
       if (arg) {
-        const proc = manager.find(arg);
+        const proc = manager.get(arg);
         if (!proc) {
           return;
         }
@@ -27,6 +27,7 @@ export function registerPsPinCommand(
         if (!processId) return;
       }
 
+      if (!processId) return;
       dockActions.setFocus(processId);
     },
   });

package/src/commands/settings/build-sections.ts

@@ -13,7 +13,7 @@ export function buildSettingsSections(
           id: "processList.maxVisibleProcesses",
           label: "Max visible processes",
           description:
-            "Maximum processes shown in the /processes list before scrolling",
+            "Maximum processes shown in the /ps list before scrolling",
           currentValue: String(
             tabConfig?.processList?.maxVisibleProcesses ??
               resolved.processList.maxVisibleProcesses,

package/src/components/log-dock-component.ts

@@ -17,8 +17,6 @@ import { LIVE_STATUSES } from "../constants";
 import type { ProcessManager } from "../manager";
 import { LogFileViewer } from "./log-file-viewer";
 
-const POLL_INTERVAL_MS = 500;
-
 const PROCESS_COLORS: ThemeColor[] = [
   "accent",
   "warning",
@@ -47,7 +45,6 @@ export class LogDockComponent implements Component {
   private mode: "collapsed" | "open";
   private focusedProcessId: string | null;
 
-  private timer: ReturnType<typeof setInterval> | null = null;
   private unsubscribeManager: (() => void) | null = null;
 
   /** One viewer per process, lazily created, follow:true. */
@@ -64,10 +61,6 @@ export class LogDockComponent implements Component {
     this.mode = options.mode;
     this.focusedProcessId = options.focusedProcessId;
 
-    this.timer = setInterval(() => {
-      this.tui.requestRender();
-    }, POLL_INTERVAL_MS);
-
     this.unsubscribeManager = this.manager.onEvent(() => {
       this.tui.requestRender();
     });
@@ -227,10 +220,6 @@ export class LogDockComponent implements Component {
   }
 
   dispose(): void {
-    if (this.timer) {
-      clearInterval(this.timer);
-      this.timer = null;
-    }
     this.unsubscribeManager?.();
     this.viewers.clear();
     this.processColors.clear();

package/src/components/log-overlay-component.ts

@@ -61,7 +61,6 @@ export class LogOverlayComponent implements Component {
   private mode: OverlayMode = "normal";
   private searchInput: Input = new Input();
 
-  private timer: ReturnType<typeof setInterval> | null = null;
   private unsubscribeManager: (() => void) | null = null;
 
   constructor(opts: LogOverlayOptions) {
@@ -91,10 +90,6 @@ export class LogOverlayComponent implements Component {
       this.tui.requestRender();
     });
 
-    this.timer = setInterval(() => {
-      this.tui.requestRender();
-    }, 300);
-
     this.searchInput.onSubmit = (query) => {
       const trimmed = query.trim();
       if (trimmed) {
@@ -163,10 +158,6 @@ export class LogOverlayComponent implements Component {
   // ---------------------------------------------------------------------------
 
   private close(): void {
-    if (this.timer) {
-      clearInterval(this.timer);
-      this.timer = null;
-    }
     this.unsubscribeManager?.();
     this.unsubscribeManager = null;
     this.done();